Merge pull request #178 from PortalTechnologiesInc/feat/age-verification-rest

feat(portal-rest): add age verification

Author: denmeh

CHANGELOG.md

@@ -14,6 +14,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 - `GET /info` now includes `version` and `git_commit` fields (previously only in `GET /version`). `GET /version` kept for backward compatibility.
 
 #### Added
+- **Age verification**: `POST /verification/sessions` creates a browser-based age verification session AND automatically starts listening for the verification token in a single call. Returns session info plus a `stream_id` to poll for the Cashu token result. Requires `[verification] api_key` in config. Relay URLs default to the `[nostr]` config if not provided.
+- **Verification token request**: `POST /verification/token` requests a verification token from a user who already holds one (e.g. mobile app verified users). Returns a `stream_id` for async polling.
+- TS SDK: `createVerificationSession()` now returns `AsyncOperation<CashuResponseStatus>` — use `poll()` or `done` to wait for the token. `requestVerificationToken()` for the mobile flow.
+- Example: `examples/age-verification.js` — simplified single-call age verification flow
 - **NIP-05 auto-registration**: if `PORTAL__PROFILE__NIP05` is set to a `@getportal.cc` address, the daemon registers it with the Portal profile service at startup (one-time, cached in `~/.portal-rest/nip05.registered`). Self-hosted domains are set in the Nostr profile only, no external call.
 
 ---

crates/portal-rest/clients/ts/src/client.ts

@@ -23,6 +23,7 @@ import {
   IssueJwtResponse,
   VerifyJwtResponse,
   CashuResponseStatus,
+  VerificationSessionResponse,
   WalletInfoResponse,
   VersionResponse,
   InfoResponse,
@@ -750,4 +751,49 @@ export class PortalClient {
     const q = after !== undefined ? `?after=${after}` : '';
     return this.get<EventsResponse>(`/events/${encodeURIComponent(streamId)}${q}`);
   }
+
+  // ---- Verification ----
+
+  /**
+   * Initiate a browser-based age verification session.
+   *
+   * Creates the verification session AND automatically starts listening for the
+   * verification token. Returns session info plus an `AsyncOperation` — use
+   * `poll()` or `done` to wait for the Cashu token result.
+   *
+   * Requires `[verification] api_key` in portal-rest config.
+   */
+  public async createVerificationSession(relayUrls?: string[]): Promise<
+    VerificationSessionResponse & AsyncOperation<CashuResponseStatus>
+  > {
+    const resp = await this.post<VerificationSessionResponse>('/verification/sessions', {
+      relays: relayUrls,
+    });
+    const done = this.registerStream(resp.stream_id).then(
+      (event) => event.status as CashuResponseStatus
+    );
+    return { ...resp, streamId: resp.stream_id, done };
+  }
+
+  // ---- Verification Token ----
+
+  /**
+   * Request a Cashu token from a recipient Portal wallet.
+   *
+   * Uses the Portal mint (`https://mint.getportal.cc`) with unit `multi`.
+   * Returns the `stream_id`; poll via `getEvents(streamId)` or use `onEvent`.
+   */
+  public async requestVerificationToken(
+    recipientKey: string,
+    subkeys: string[]
+  ): Promise<AsyncOperation<CashuResponseStatus>> {
+    const resp = await this.post<{ stream_id: string }>('/verification/token', {
+      recipient_key: recipientKey,
+      subkeys,
+    });
+    const done = this.registerStream(resp.stream_id).then(
+      (event) => event.status as CashuResponseStatus
+    );
+    return { streamId: resp.stream_id, done };
+  }
 }

crates/portal-rest/clients/ts/src/index.ts

@@ -60,6 +60,13 @@ export {
   BurnCashuRequest,
   CashuResponseStatus,
 
+  // Verification
+  CreateVerificationSessionRequest,
+  VerificationSessionResponse,
+
+  // Portal Token
+  RequestVerificationTokenRequest,
+
   // Relays
   RelayRequest,
 

crates/portal-rest/clients/ts/src/types.ts

@@ -321,6 +321,28 @@ export type CashuResponseStatus =
   | { status: 'insufficient_funds' }
   | { status: 'rejected'; reason?: string };
 
+// ---- Verification ----
+
+export interface CreateVerificationSessionRequest {
+  /** Relay URLs to use for the verification session. Defaults to the relays configured in the [nostr] section of the config if omitted. */
+  relays?: string[];
+}
+
+export interface VerificationSessionResponse {
+  session_id: string;
+  session_url: string;
+  ephemeral_npub: string;
+  expires_at: number;
+  stream_id: string;
+}
+
+// ---- Portal Token (Cashu from Portal wallet) ----
+
+export interface RequestVerificationTokenRequest {
+  recipient_key: string;
+  subkeys: string[];
+}
+
 // ---- Relays ----
 
 export interface RelayRequest {

crates/portal-rest/example.config.toml

@@ -52,6 +52,12 @@ ln_backend = "none"
 path = "portal-rest.db"
 
 
+## Age verification settings. Required for the POST /verification/sessions endpoint.
+## Get your API key from https://verify.getportal.cc
+# [verification]
+# api_key = "your-api-key-here"
+
+
 ## Optional Nostr profile metadata. Set any combination of fields to publish
 ## your profile on the Nostr network at startup. Omit the section or leave
 ## fields commented out to skip.

crates/portal-rest/openapi.yaml

@@ -409,6 +409,53 @@ components:
           type: string
       additionalProperties: true
 
+    CreateVerificationSessionRequest:
+      type: object
+      properties:
+        relays:
+          type: array
+          items:
+            type: string
+          description: |
+            Relay WebSocket URLs for the verification session.
+            Defaults to the relays configured in the [nostr] section of the config if omitted.
+
+    VerificationSessionResponse:
+      type: object
+      required: [session_id, session_url, ephemeral_npub, expires_at, stream_id]
+      properties:
+        session_id:
+          type: string
+          description: Unique verification session identifier
+        session_url:
+          type: string
+          description: URL to redirect the user to for verification
+        ephemeral_npub:
+          type: string
+          description: Ephemeral Nostr public key for this session
+        expires_at:
+          type: integer
+          format: uint64
+          description: Unix timestamp when the session expires
+        stream_id:
+          type: string
+          description: Stream ID to poll for the verification token result via GET /events/{stream_id}
+
+    RequestVerificationTokenRequest:
+      type: object
+      required: [recipient_key, subkeys]
+      properties:
+        recipient_key:
+          type: string
+          description: Hex-encoded recipient public key
+        subkeys:
+          type: array
+          items:
+            type: string
+          description: Optional subkeys to include
+      description: |
+        Request a verification token from a recipient Portal wallet.
+
 paths:
   /health:
     get:
@@ -928,3 +975,70 @@ paths:
                         $ref: '#/components/schemas/EventsResponse'
         "404":
           description: Stream not found
+
+
+  /verification/sessions:
+    post:
+      tags:
+        - Verification
+      summary: Initiate a browser-based age verification session
+      description: |
+        Creates a verification session AND automatically starts listening for the
+        verification token. Returns session info (including `session_url` to redirect
+        the user to) plus a `stream_id` to poll for the Cashu token result.
+        Poll `GET /events/{stream_id}` for a `cashu_response` event containing the token.
+        Requires `[verification] api_key` in the portal-rest configuration.
+      requestBody:
+        required: false
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateVerificationSessionRequest'
+      responses:
+        "200":
+          description: Verification session created
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: '#/components/schemas/ApiResponse'
+                  - properties:
+                      data:
+                        $ref: '#/components/schemas/VerificationSessionResponse'
+        "400":
+          description: Verification not configured or invalid request
+        "500":
+          description: Verification service error
+
+  /verification/token:
+    post:
+      tags:
+        - Verification
+      summary: Request a verification token from a user who already holds one
+      description: |
+        Requests a verification token (Cashu) from a recipient who already has a token
+        in their Portal wallet (e.g. a mobile app user who completed verification previously).
+        Uses the Portal mint (`https://mint.getportal.cc`) with unit `multi`. Returns a
+        stream_id for polling. Poll GET /events/{stream_id} for the `cashu_response` event.
+
+        For new browser-based verification, use `POST /verification/sessions` instead — it
+        handles the full flow (session creation + token listening) in a single call.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RequestVerificationTokenRequest'
+      responses:
+        "201":
+          description: Verification token request initiated
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: '#/components/schemas/ApiResponse'
+                  - properties:
+                      data:
+                        $ref: '#/components/schemas/StreamIdResponse'
+        "400":
+          description: Invalid recipient key or subkeys

crates/portal-rest/src/command.rs

@@ -74,6 +74,19 @@ pub struct RequestCashuRequest {
     pub amount: u64,
 }
 
+#[derive(Debug, Deserialize)]
+pub struct CreateVerificationSessionRequest {
+    /// Relay URLs to use for the verification session. Defaults to
+    /// the relays configured in the `[nostr]` section of the config if not set.
+    pub relays: Option<Vec<String>>,
+}
+
+#[derive(Debug, Deserialize)]
+pub struct RequestVerificationTokenRequest {
+    pub recipient_key: String,
+    pub subkeys: Vec<String>,
+}
+
 #[derive(Debug, Deserialize)]
 pub struct SendCashuDirectRequest {
     pub main_key: String,

crates/portal-rest/src/config.rs

@@ -18,6 +18,13 @@ pub struct Settings {
     pub profile: ProfileSettings,
     #[serde(default)]
     pub logging: LoggingSettings,
+    #[serde(default)]
+    pub verification: Option<VerificationSettings>,
+}
+
+#[derive(Deserialize, Debug, Clone)]
+pub struct VerificationSettings {
+    pub api_key: String,
 }
 
 #[derive(Deserialize, Debug, Clone)]