@portpowered/reference-data 0.4.10 → 0.4.12

package/generated/openapi.json

@@ -7835,12 +7835,12 @@
           {
             "in": "query",
             "name": "resource",
-            "required": true,
+            "required": false,
             "schema": {
               "type": "string",
               "format": "uri"
             },
-            "description": "Canonical issuer for REST or issuer/mcp for MCP; discover rather than guess."
+            "description": "Canonical issuer for REST or issuer/mcp for MCP. Omission defaults to REST."
           },
           {
             "in": "query",
@@ -7863,7 +7863,7 @@
           }
         ],
         "responses": {
-          "303": {
+          "302": {
             "description": "Navigate to sign-in and pending consent.",
             "headers": {
               "Location": {
@@ -7924,7 +7924,7 @@
         },
         "responses": {
           "200": {
-            "description": "Callback navigation URL containing code or denial and original state.",
+            "description": "One-time browser continuation URL. Navigate the browser to receive a 302 to the registered callback.",
             "content": {
               "application/json": {
                 "schema": {
@@ -7940,7 +7940,7 @@
                   }
                 },
                 "example": {
-                  "redirect_url": "http://127.0.0.1:8765/callback?code=SERVER_ISSUED_CODE&state=ORIGINAL_STATE"
+                  "redirect_url": "https://portos-pilot-api-685761720421.us-west1.run.app/oauth/authorization-response?request_id=SERVER_ISSUED_RESPONSE_ID"
                 }
               }
             }
@@ -8036,6 +8036,57 @@
         }
       }
     },
+    "/oauth/authorization-response": {
+      "get": {
+        "operationId": "deliverOAuthAuthorizationResponse",
+        "tags": [
+          "Auth"
+        ],
+        "security": [],
+        "x-portos-resource-permission": false,
+        "x-portos-delegated": false,
+        "summary": "Redirect the browser to the approved OAuth callback",
+        "description": "Navigate the browser here using the continuation returned by authenticated\nconsent. The opaque reference expires after two minutes and is consumed once.\nThe server chooses the stored callback; caller-supplied redirect destinations\nare never used. Approval carries code, original state and issuer; denial\ncarries access_denied, original state and issuer. No bearer token is needed.\n",
+        "parameters": [
+          {
+            "in": "query",
+            "name": "request_id",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "302": {
+            "description": "Navigate with GET to the exact registered callback.",
+            "headers": {
+              "Location": {
+                "schema": {
+                  "type": "string",
+                  "format": "uri"
+                }
+              },
+              "Cache-Control": {
+                "schema": {
+                  "type": "string"
+                },
+                "description": "no-store"
+              },
+              "Referrer-Policy": {
+                "schema": {
+                  "type": "string"
+                },
+                "description": "no-referrer"
+              }
+            }
+          },
+          "400": {
+            "description": "Missing, wrong-stage, expired or consumed continuation reference."
+          }
+        }
+      }
+    },
     "/oauth/validate-request": {
       "post": {
         "operationId": "validateOAuthRequest",
@@ -13361,6 +13412,16 @@
         "type": "object",
         "additionalProperties": false
       },
+      "MediaPlayerInterfaceTransferPlaybackMessage": {
+        "x-namespace": "port1/systems/zero/capability-interfaces/media-player",
+        "x-name": "transfer-playback",
+        "x-version": "1.0",
+        "x-type": "message",
+        "x-directionality": "in",
+        "description": "Move the current playback session of the destination route's connected provider account to this one destination, preserving playing or paused state and media context. Select an advertised destination route. This affects that account's current session; it does not copy media, restart playback, transfer between providers or accounts, or fan out to group members. Read fresh source and destination state before and after dispatch to verify the move. An unavailable target requires an explicit choice of another destination.",
+        "type": "object",
+        "additionalProperties": false
+      },
       "MediaPlayerInterfaceSearchAndPlayMessage": {
         "x-namespace": "port1/systems/zero/capability-interfaces/media-player",
         "x-name": "search-and-play",
@@ -16706,36 +16767,212 @@
         ],
         "additionalProperties": false
       },
+      "RemindersProviderInterfaceCreateReminderMessage": {
+        "title": "RemindersProviderInterfaceCreateReminderMessage",
+        "x-namespace": "port1/systems/zero/capability-interfaces/reminders-provider",
+        "x-name": "create-reminder",
+        "x-version": "1.0",
+        "x-type": "message",
+        "x-directionality": "in",
+        "description": "Create a reminder in a discovered list. Creation is sent once; refresh before retrying an uncertain result.",
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "listId": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Discovered list identifier."
+          },
+          "title": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Reminder title."
+          },
+          "notes": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "listId",
+          "title"
+        ]
+      },
+      "RemindersProviderInterfaceCreateReminderResponseMessage": {
+        "title": "RemindersProviderInterfaceCreateReminderResponseMessage",
+        "x-namespace": "port1/systems/zero/capability-interfaces/reminders-provider",
+        "x-name": "create-reminder-response",
+        "x-version": "1.0",
+        "x-type": "message",
+        "x-directionality": "out",
+        "description": "The provider accepted the reminder change.",
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "reminder": {
+            "$ref": "#/components/schemas/Reminder"
+          }
+        },
+        "required": [
+          "reminder"
+        ]
+      },
+      "RemindersProviderInterfaceUpdateReminderMessage": {
+        "title": "RemindersProviderInterfaceUpdateReminderMessage",
+        "x-namespace": "port1/systems/zero/capability-interfaces/reminders-provider",
+        "x-name": "update-reminder",
+        "x-version": "1.0",
+        "x-type": "message",
+        "x-directionality": "in",
+        "description": "Edit a reminder using its last observed revision; omitted fields are preserved.",
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "reminderId": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Reminder identifier."
+          },
+          "revision": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Revision from the latest listing."
+          },
+          "title": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Replacement title."
+          },
+          "notes": {
+            "type": "string"
+          },
+          "completed": {
+            "type": "boolean"
+          }
+        },
+        "required": [
+          "reminderId",
+          "revision"
+        ]
+      },
+      "RemindersProviderInterfaceUpdateReminderResponseMessage": {
+        "title": "RemindersProviderInterfaceUpdateReminderResponseMessage",
+        "x-namespace": "port1/systems/zero/capability-interfaces/reminders-provider",
+        "x-name": "update-reminder-response",
+        "x-version": "1.0",
+        "x-type": "message",
+        "x-directionality": "out",
+        "description": "The provider accepted the reminder change.",
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "reminder": {
+            "$ref": "#/components/schemas/Reminder"
+          }
+        },
+        "required": [
+          "reminder"
+        ]
+      },
+      "RemindersProviderInterfaceDeleteReminderMessage": {
+        "title": "RemindersProviderInterfaceDeleteReminderMessage",
+        "x-namespace": "port1/systems/zero/capability-interfaces/reminders-provider",
+        "x-name": "delete-reminder",
+        "x-version": "1.0",
+        "x-type": "message",
+        "x-directionality": "in",
+        "description": "Soft-delete a reminder using its last observed revision.",
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "reminderId": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Reminder identifier."
+          },
+          "revision": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Revision from the latest listing."
+          }
+        },
+        "required": [
+          "reminderId",
+          "revision"
+        ]
+      },
+      "RemindersProviderInterfaceDeleteReminderResponseMessage": {
+        "title": "RemindersProviderInterfaceDeleteReminderResponseMessage",
+        "x-namespace": "port1/systems/zero/capability-interfaces/reminders-provider",
+        "x-name": "delete-reminder-response",
+        "x-version": "1.0",
+        "x-type": "message",
+        "x-directionality": "out",
+        "description": "The provider accepted soft deletion of the reminder.",
+        "type": "object",
+        "additionalProperties": false
+      },
       "RemindersProviderInterfaceListRemindersMessage": {
+        "title": "RemindersProviderInterfaceListRemindersMessage",
         "x-namespace": "port1/systems/zero/capability-interfaces/reminders-provider",
         "x-name": "list-reminders",
         "x-version": "1.0",
         "x-type": "message",
         "x-directionality": "in",
-        "description": "Request to list reminders from a reminders provider",
+        "description": "List reminder lists and their reminders. Omit listId to enumerate all lists.",
         "type": "object",
-        "additionalProperties": false
+        "additionalProperties": false,
+        "properties": {
+          "listId": {
+            "type": "string",
+            "minLength": 1,
+            "description": "List identifier from a previous listing."
+          },
+          "includeCompleted": {
+            "type": "boolean",
+            "default": false
+          },
+          "cursor": {
+            "type": "string",
+            "description": "Opaque next-page cursor."
+          },
+          "maxResults": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 1000
+          }
+        }
       },
       "RemindersProviderInterfaceListRemindersResponseMessage": {
+        "title": "RemindersProviderInterfaceListRemindersResponseMessage",
         "x-namespace": "port1/systems/zero/capability-interfaces/reminders-provider",
         "x-name": "list-reminders-response",
         "x-version": "1.0",
         "x-type": "message",
         "x-directionality": "out",
-        "description": "Response containing a list of reminder lists from a reminders provider",
+        "description": "Reminder lists and one bounded page of reminders.",
         "type": "object",
+        "additionalProperties": false,
         "properties": {
           "reminderLists": {
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/ReminderList"
             }
+          },
+          "reminders": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/Reminder"
+            }
+          },
+          "nextCursor": {
+            "type": "string"
           }
         },
         "required": [
-          "reminderLists"
-        ],
-        "additionalProperties": false
+          "reminderLists",
+          "reminders"
+        ]
       },
       "ControlRouteGroupsProviderInterfaceCreateGroupMessage": {
         "x-namespace": "port1/systems/zero/capability-interfaces/control-route-groups-provider",
@@ -18155,6 +18392,11 @@
           },
           "name": {
             "type": "string"
+          },
+          "positionMs": {
+            "description": "Provider-observed position within the current media item in milliseconds. Omitted when unknown. Compare fresh observations with media identity and playback state; a track transition does not prove continuity.",
+            "type": "integer",
+            "minimum": 0
           }
         },
         "required": [
@@ -28381,6 +28623,38 @@
           "albumId"
         ]
       },
+      "Reminder": {
+        "type": "object",
+        "additionalProperties": false,
+        "description": "A reminder and its current provider revision for guarded edits.",
+        "properties": {
+          "reminderId": {
+            "type": "string"
+          },
+          "listId": {
+            "type": "string"
+          },
+          "title": {
+            "type": "string"
+          },
+          "notes": {
+            "type": "string"
+          },
+          "completed": {
+            "type": "boolean"
+          },
+          "revision": {
+            "type": "string",
+            "description": "Omitted when the provider does not supply a revision; writes require it."
+          }
+        },
+        "required": [
+          "reminderId",
+          "listId",
+          "title",
+          "completed"
+        ]
+      },
       "ReminderList": {
         "type": "object",
         "description": "A reminder list",

package/generated/public/docs/for-ai/api-catalog.md

@@ -84,7 +84,8 @@ To request the complete rendered catalog, fetch `/api/?full=1` with an HTML-comp
 | [GET /oauth-clients](/docs/for-ai/operations/enumerateOAuthClients.md) | OAuth (no scope) | query:nextToken, query:maxResults, query:expand | — |
 | [POST /oauth-clients](/docs/for-ai/operations/createOAuthClient.md) | OAuth (no scope) | — | allowedOrigins, clientName, clientUri, clientUriLocalized, contacts, grantTypes, jwks, jwksUri, logoUri, logoUriLocalized, policyUri, policyUriLocalized, redirectUris, responseTypes, scope, scopes, softwareId, softwareVersion, tokenEndpointAuthMethod, tokenEndpointAuthSigningAlg, tosUri, tosUriLocalized |
 | [GET /oauth/authorization-request](/docs/for-ai/operations/getPendingOAuthConsent.md) | See session/security contract | query:request_id (required) | — |
-| [GET /oauth/authorize](/docs/for-ai/operations/beginOAuthAuthorization.md) | Public | query:client_id (required), query:redirect_uri (required), query:response_type (required), query:scope (required), query:state (required), query:resource (required), query:code_challenge (required), query:code_challenge_method (required) | — |
+| [GET /oauth/authorization-response](/docs/for-ai/operations/deliverOAuthAuthorizationResponse.md) | Public | query:request_id (required) | — |
+| [GET /oauth/authorize](/docs/for-ai/operations/beginOAuthAuthorization.md) | Public | query:client_id (required), query:redirect_uri (required), query:response_type (required), query:scope (required), query:state (required), query:resource, query:code_challenge (required), query:code_challenge_method (required) | — |
 | [POST /oauth/authorize](/docs/for-ai/operations/completeOAuthConsent.md) | See session/security contract | — | approved, request_id, scope |
 | [POST /oauth/authorize-device](/docs/for-ai/operations/authorizeDevice.md) | OAuth (no scope) | — | scopes, user_code |
 | [POST /oauth/generate-code](/docs/for-ai/operations/generateOAuthCode.md) | OAuth (no scope) | — | client_id, code_challenge, code_challenge_method, redirect_uri, scopes, state |

package/generated/public/docs/for-ai/capability-interfaces/media-player/1.0.md

@@ -27,6 +27,7 @@ Read scopes: endpoint:read. Inbound control scope: message:send. Resource permis
 - [skip-forward](/docs/references/capability-interfaces/media-player/1.0/messages/skip-forward.yaml) (in): Use this exact payload schema.
 - [start-over](/docs/references/capability-interfaces/media-player/1.0/messages/start-over.yaml) (in): Use this exact payload schema.
 - [stop](/docs/references/capability-interfaces/media-player/1.0/messages/stop.yaml) (in): Use this exact payload schema.
+- [transfer-playback](/docs/references/capability-interfaces/media-player/1.0/messages/transfer-playback.yaml) (in): Move the current playback session of the destination route's connected provider account to this one destination, preserving playing or paused state and media context. Select an advertised destination route. This affects that account's current session; it does not copy media, restart playback, transfer between providers or accounts, or fan out to group members. Read fresh source and destination state before and after dispatch to verify the move. An unavailable target requires an explicit choice of another destination.
 
 ## State attributes
 

package/generated/public/docs/for-ai/capability-interfaces/reminders-provider/1.0.md

@@ -10,8 +10,14 @@ Read scopes: endpoint:read. Inbound control scope: message:send. Resource permis
 
 ## Messages
 
-- [list-reminders](/docs/references/capability-interfaces/reminders-provider/1.0/messages/list-reminders.yaml) (in): Request to list reminders from a reminders provider
-- [list-reminders-response](/docs/references/capability-interfaces/reminders-provider/1.0/messages/list-reminders-response.yaml) (out): Response containing a list of reminder lists from a reminders provider
+- [create-reminder](/docs/references/capability-interfaces/reminders-provider/1.0/messages/create-reminder.yaml) (in): Create a reminder in a discovered list. Creation is sent once; refresh before retrying an uncertain result.
+- [create-reminder-response](/docs/references/capability-interfaces/reminders-provider/1.0/messages/create-reminder-response.yaml) (out): The provider accepted the reminder change.
+- [delete-reminder](/docs/references/capability-interfaces/reminders-provider/1.0/messages/delete-reminder.yaml) (in): Soft-delete a reminder using its last observed revision.
+- [delete-reminder-response](/docs/references/capability-interfaces/reminders-provider/1.0/messages/delete-reminder-response.yaml) (out): The provider accepted soft deletion of the reminder.
+- [list-reminders](/docs/references/capability-interfaces/reminders-provider/1.0/messages/list-reminders.yaml) (in): List reminder lists and their reminders. Omit listId to enumerate all lists.
+- [list-reminders-response](/docs/references/capability-interfaces/reminders-provider/1.0/messages/list-reminders-response.yaml) (out): Reminder lists and one bounded page of reminders.
+- [update-reminder](/docs/references/capability-interfaces/reminders-provider/1.0/messages/update-reminder.yaml) (in): Edit a reminder using its last observed revision; omitted fields are preserved.
+- [update-reminder-response](/docs/references/capability-interfaces/reminders-provider/1.0/messages/update-reminder-response.yaml) (out): The provider accepted the reminder change.
 
 ## State attributes
 

package/generated/public/docs/for-ai/guides/authentication-and-dcr.md

@@ -27,7 +27,7 @@ This discovery step is shared by every client. The deployed pilot API is https:/
 
 An MCP connector can start at https://api.portoperatingsystem.lol/mcp and follow its WWW-Authenticate resource_metadata URL. Fetch that public metadata and the authorization server it names. MCP initialization alone does not prove that the account's devices are accessible. Never use a REST token on MCP or an MCP token on REST.
 
-Choose the transport before authorizing. Keep its resource unchanged through authorization, token exchange and refresh. If a REST request fails because you authorized the MCP resource (or the reverse), obtain a new user authorization for the correct resource. Refresh cannot change the token's audience.
+Choose the transport before authorizing. Omitting resource at authorization selects REST. Supply the discovered resource explicitly to select MCP. Code exchange and refresh may omit resource and inherit the grant audience; an explicit resource must stay unchanged. If a REST request fails because you authorized the MCP resource (or the reverse), obtain a new user authorization for the correct resource. Refresh cannot change the token's audience.
 
 Choose one supported [client registration method](/docs/for-ai/guides/oauth-client-registration.md), then follow the same [consent and callback steps](/docs/for-ai/guides/oauth-consent-and-callback.md). If metadata omits registration_endpoint, new DCR registration is unavailable; do not guess a replacement endpoint or silently switch to another client's credentials.
 
@@ -45,7 +45,7 @@ const resource = authorizationServer.issuer;
 const apiBase = authorizationServer.issuer;
 ```
 
-For MCP, assign `resource` from the protected-resource metadata's `resource` field instead. Do not replace either value with the hostname you started from. A wrong `resource` can produce an `invalid_request` error callback even when client registration succeeded.
+For MCP, assign `resource` from the protected-resource metadata's `resource` field instead. Do not replace either value with the hostname you started from. A wrong `resource` can produce an `invalid_target` error callback even when client registration succeeded.
 
 Canonical component: [Discover the OAuth server and choose REST or MCP](/docs/for-ai/guides/oauth-discovery.md).
 
@@ -81,6 +81,8 @@ Canonical component: [Register an OAuth client with DCR or CIMD](/docs/for-ai/gu
 
 Use the endpoints and resource from [discovery](/docs/for-ai/guides/oauth-discovery.md) and the client ID and exact callback from [registration](/docs/for-ai/guides/oauth-client-registration.md). These steps are identical for DCR and CIMD, REST and MCP; the chosen resource is the transport-specific input.
 
+`resource` is optional. Omitting it selects the canonical REST audience (the authorization-server issuer). For MCP, supply its discovered `/mcp` resource explicitly. Token exchange and refresh can omit `resource` and inherit the audience bound to the authorization code or refresh token. Explicit mismatches are rejected as `invalid_target`.
+
 1. Start the callback handler the client controls. For a loopback callback, bind its listener locally before opening authorization.
 2. Generate a cryptographically random PKCE verifier of 43–128 permitted characters. Compute code_challenge = BASE64URL(SHA256(verifier)), without padding. Generate a separate random state and retain both in this authorization attempt.
 3. Open the discovered authorization_endpoint with the following query parameters. Percent-encode parameter values; do not append raw callback URLs or scopes into an unescaped query.
@@ -117,7 +119,27 @@ authorizationURL.search = new URLSearchParams({
 
 The user signs in on Port OS and reviews the requested permissions. Pause for the user; an agent must not approve its own grant, request passwords or manufacture a production sign-in identity. Local functional tests substitute an existing signed fixture identity at this boundary without changing production sign-in.
 
-After approval, Port OS navigates to the exact callback with code, state and iss. Reject a callback whose state or issuer does not match this attempt. Treat an error callback as a denied or failed authorization, not a code. Codes and pending consent expire after ten minutes and are single-use. Do not paste codes or credentials into shared chat or logs. Continue with [code exchange and token lifecycle](/docs/for-ai/guides/oauth-token-lifecycle.md).
+After approval, the consent page navigates to a one-time Port OS continuation.
+That endpoint returns HTTP 302 Found with the exact registered callback in
+Location, carrying code, original state and iss. Denial uses the same 302 handoff
+with access_denied instead of a code. The authenticated consent fetch returns
+200 JSON only for the intermediate continuation; it must be followed by document
+navigation, not another fetch. Continuations expire after two minutes and are
+single-use. They require no login token and cannot be used to approve consent.
+
+Reject a callback whose state or issuer does not match this attempt. Treat an
+error callback as a denied or failed authorization, not a code. Codes and pending
+consent expire after ten minutes and are single-use. Do not paste codes,
+continuation references or credentials into shared chat or logs. Continue with
+[code exchange and token lifecycle](/docs/for-ai/guides/oauth-token-lifecycle.md).
+
+For hosted-client acceptance, preserve the browser network log and approve a
+fresh request. Verify the document request to /oauth/authorization-response
+returns 302, the next GET reaches the registered client callback, and the client
+posts its code and original PKCE verifier to the discovered token endpoint.
+Repeat with Deny and verify access_denied without a code. Backend functional and
+website browser tests cover these boundaries against an isolated callback;
+compatibility with a specific hosted client still requires that live trace.
 
 Canonical component: [Obtain user consent and validate the OAuth callback](/docs/for-ai/guides/oauth-consent-and-callback.md).
 
@@ -151,7 +173,7 @@ const tokens = await tokenResponse.json(); // Store securely; do not print token
 
 Save access_token, refresh_token and returned scope in the connector's secure credential store. Public clients have no client secret. Use Authorization: Bearer <access_token> with REST requests or the MCP HTTP connection, according to that token's resource. A refresh token is never an API credential. [Scopes bound access; resource policies still apply](/docs/for-ai/guides/authorization-rules.md).
 
-Refresh with grant_type=refresh_token, client_id, refresh_token and the original resource at token_endpoint. Scope may stay the same or narrow; it cannot expand. Credentials rotate: store the newly returned refresh token atomically and stop using the previous one. A revoked or reused refresh token must not be retried in a loop. Reauthorize when the grant no longer permits the intended operation.
+Refresh with grant_type=refresh_token, client_id and refresh_token at token_endpoint. The resource parameter is optional for code exchange and refresh: omission inherits the existing grant audience; if supplied, it must match the original resource. Scope may stay the same or narrow; it cannot expand. Credentials rotate: store the newly returned refresh token atomically and stop using the previous one. A revoked or reused refresh token must not be retried in a loop. Reauthorize when the grant no longer permits the intended operation.
 
 Revoke by POSTing application/x-www-form-urlencoded token=<refresh_token>&client_id=<client_id> to revocation_endpoint. Revoked grants stop authorizing both access and refresh requests. Removing a local configuration file alone is not server-side revocation.
 

package/generated/public/docs/for-ai/guides/oauth-consent-and-callback.md

@@ -2,6 +2,8 @@
 
 Use the endpoints and resource from [discovery](/docs/for-ai/guides/oauth-discovery.md) and the client ID and exact callback from [registration](/docs/for-ai/guides/oauth-client-registration.md). These steps are identical for DCR and CIMD, REST and MCP; the chosen resource is the transport-specific input.
 
+`resource` is optional. Omitting it selects the canonical REST audience (the authorization-server issuer). For MCP, supply its discovered `/mcp` resource explicitly. Token exchange and refresh can omit `resource` and inherit the audience bound to the authorization code or refresh token. Explicit mismatches are rejected as `invalid_target`.
+
 1. Start the callback handler the client controls. For a loopback callback, bind its listener locally before opening authorization.
 2. Generate a cryptographically random PKCE verifier of 43–128 permitted characters. Compute code_challenge = BASE64URL(SHA256(verifier)), without padding. Generate a separate random state and retain both in this authorization attempt.
 3. Open the discovered authorization_endpoint with the following query parameters. Percent-encode parameter values; do not append raw callback URLs or scopes into an unescaped query.
@@ -38,4 +40,24 @@ authorizationURL.search = new URLSearchParams({
 
 The user signs in on Port OS and reviews the requested permissions. Pause for the user; an agent must not approve its own grant, request passwords or manufacture a production sign-in identity. Local functional tests substitute an existing signed fixture identity at this boundary without changing production sign-in.
 
-After approval, Port OS navigates to the exact callback with code, state and iss. Reject a callback whose state or issuer does not match this attempt. Treat an error callback as a denied or failed authorization, not a code. Codes and pending consent expire after ten minutes and are single-use. Do not paste codes or credentials into shared chat or logs. Continue with [code exchange and token lifecycle](/docs/for-ai/guides/oauth-token-lifecycle.md).
+After approval, the consent page navigates to a one-time Port OS continuation.
+That endpoint returns HTTP 302 Found with the exact registered callback in
+Location, carrying code, original state and iss. Denial uses the same 302 handoff
+with access_denied instead of a code. The authenticated consent fetch returns
+200 JSON only for the intermediate continuation; it must be followed by document
+navigation, not another fetch. Continuations expire after two minutes and are
+single-use. They require no login token and cannot be used to approve consent.
+
+Reject a callback whose state or issuer does not match this attempt. Treat an
+error callback as a denied or failed authorization, not a code. Codes and pending
+consent expire after ten minutes and are single-use. Do not paste codes,
+continuation references or credentials into shared chat or logs. Continue with
+[code exchange and token lifecycle](/docs/for-ai/guides/oauth-token-lifecycle.md).
+
+For hosted-client acceptance, preserve the browser network log and approve a
+fresh request. Verify the document request to /oauth/authorization-response
+returns 302, the next GET reaches the registered client callback, and the client
+posts its code and original PKCE verifier to the discovered token endpoint.
+Repeat with Deny and verify access_denied without a code. Backend functional and
+website browser tests cover these boundaries against an isolated callback;
+compatibility with a specific hosted client still requires that live trace.

package/generated/public/docs/for-ai/guides/oauth-discovery.md

@@ -9,7 +9,7 @@ This discovery step is shared by every client. The deployed pilot API is https:/
 
 An MCP connector can start at https://api.portoperatingsystem.lol/mcp and follow its WWW-Authenticate resource_metadata URL. Fetch that public metadata and the authorization server it names. MCP initialization alone does not prove that the account's devices are accessible. Never use a REST token on MCP or an MCP token on REST.
 
-Choose the transport before authorizing. Keep its resource unchanged through authorization, token exchange and refresh. If a REST request fails because you authorized the MCP resource (or the reverse), obtain a new user authorization for the correct resource. Refresh cannot change the token's audience.
+Choose the transport before authorizing. Omitting resource at authorization selects REST. Supply the discovered resource explicitly to select MCP. Code exchange and refresh may omit resource and inherit the grant audience; an explicit resource must stay unchanged. If a REST request fails because you authorized the MCP resource (or the reverse), obtain a new user authorization for the correct resource. Refresh cannot change the token's audience.
 
 Choose one supported [client registration method](/docs/for-ai/guides/oauth-client-registration.md), then follow the same [consent and callback steps](/docs/for-ai/guides/oauth-consent-and-callback.md). If metadata omits registration_endpoint, new DCR registration is unavailable; do not guess a replacement endpoint or silently switch to another client's credentials.
 
@@ -27,4 +27,4 @@ const resource = authorizationServer.issuer;
 const apiBase = authorizationServer.issuer;
 ```
 
-For MCP, assign `resource` from the protected-resource metadata's `resource` field instead. Do not replace either value with the hostname you started from. A wrong `resource` can produce an `invalid_request` error callback even when client registration succeeded.
+For MCP, assign `resource` from the protected-resource metadata's `resource` field instead. Do not replace either value with the hostname you started from. A wrong `resource` can produce an `invalid_target` error callback even when client registration succeeded.

package/generated/public/docs/for-ai/guides/oauth-token-lifecycle.md

@@ -28,7 +28,7 @@ const tokens = await tokenResponse.json(); // Store securely; do not print token
 
 Save access_token, refresh_token and returned scope in the connector's secure credential store. Public clients have no client secret. Use Authorization: Bearer <access_token> with REST requests or the MCP HTTP connection, according to that token's resource. A refresh token is never an API credential. [Scopes bound access; resource policies still apply](/docs/for-ai/guides/authorization-rules.md).
 
-Refresh with grant_type=refresh_token, client_id, refresh_token and the original resource at token_endpoint. Scope may stay the same or narrow; it cannot expand. Credentials rotate: store the newly returned refresh token atomically and stop using the previous one. A revoked or reused refresh token must not be retried in a loop. Reauthorize when the grant no longer permits the intended operation.
+Refresh with grant_type=refresh_token, client_id and refresh_token at token_endpoint. The resource parameter is optional for code exchange and refresh: omission inherits the existing grant audience; if supplied, it must match the original resource. Scope may stay the same or narrow; it cannot expand. Credentials rotate: store the newly returned refresh token atomically and stop using the previous one. A revoked or reused refresh token must not be retried in a loop. Reauthorize when the grant no longer permits the intended operation.
 
 Revoke by POSTing application/x-www-form-urlencoded token=<refresh_token>&client_id=<client_id> to revocation_endpoint. Revoked grants stop authorizing both access and refresh requests. Removing a local configuration file alone is not server-side revocation.
 

package/generated/public/docs/for-ai/operations/beginOAuthAuthorization.md

@@ -72,11 +72,11 @@ get:
         type: string
     - in: query
       name: resource
-      required: true
+      required: false
       schema:
         type: string
         format: uri
-      description: Canonical issuer for REST or issuer/mcp for MCP; discover rather than guess.
+      description: Canonical issuer for REST or issuer/mcp for MCP. Omission defaults to REST.
     - in: query
       name: code_challenge
       required: true
@@ -90,7 +90,7 @@ get:
         enum:
           - S256
   responses:
-    '303':
+    '302':
       description: Navigate to sign-in and pending consent.
       headers:
         Location:

package/generated/public/docs/for-ai/operations/completeOAuthConsent.md

@@ -61,7 +61,9 @@ post:
           approved: true
   responses:
     '200':
-      description: Callback navigation URL containing code or denial and original state.
+      description: >-
+        One-time browser continuation URL. Navigate the browser to receive a 302 to the registered
+        callback.
       content:
         application/json:
           schema:
@@ -73,7 +75,8 @@ post:
                 type: string
                 format: uri
           example:
-            redirect_url: http://127.0.0.1:8765/callback?code=SERVER_ISSUED_CODE&state=ORIGINAL_STATE
+            redirect_url: >-
+              https://portos-pilot-api-685761720421.us-west1.run.app/oauth/authorization-response?request_id=SERVER_ISSUED_RESPONSE_ID
     '400':
       description: Invalid, expired or consumed request.
     '401':