@wildo-ai/saas-models 1.1.4 → 1.1.5

package/dist/esm/requests/idempotency-key.shared.js

@@ -0,0 +1,112 @@
+/**
+ * The `Idempotency-Key` request header: its vocabulary, its bounds and its one parser (#535).
+ *
+ * A caller that sends the same key again is asking for the outcome of the FIRST request, not for a second execution. An
+ * operation variant declares whether it takes the header ({@link ResourceOperationIdempotencyKeyRequirement}); the
+ * framework parses and bounds the value here, refuses a malformed or undeclared one, and hands the key to the operation's
+ * implementation, which owns what "the same request" means for its effects (a billing mutation, for example, replays the
+ * committed change and refuses the same key sent with a different request).
+ *
+ * Shared by the backend controller that reads the header, the frontend client that writes it and the OpenAPI projection
+ * that documents it, so the three cannot disagree about what a key is.
+ *
+ * spec-cite: draft-ietf-httpapi-idempotency-key-header-07 (2025-10-15), https://datatracker.ietf.org/doc/html/draft-ietf-httpapi-idempotency-key-header
+ * — the header name, its String value, and the 400/409/422 outcomes are taken from that draft; the wording here is this
+ * repository's own.
+ */
+/** Whether an operation variant takes the `Idempotency-Key` request header. Absent on a variant: it takes none. */
+export var ResourceOperationIdempotencyKeyRequirement;
+(function (ResourceOperationIdempotencyKeyRequirement) {
+    /**
+     * The header is honored when a caller sends it, and a request without it runs unkeyed. For an operation whose effect
+     * converges when repeated (cancelling, resuming), so an unkeyed retry is safe even though it is not deduplicated.
+     */
+    ResourceOperationIdempotencyKeyRequirement["ACCEPTED"] = "accepted";
+    /**
+     * A request without the header is refused with 400 before anything runs. For an operation whose repeat is a second,
+     * different effect (adding an add-on twice adds two), where an unkeyed retry is exactly the duplicate the key prevents.
+     */
+    ResourceOperationIdempotencyKeyRequirement["REQUIRED"] = "required";
+})(ResourceOperationIdempotencyKeyRequirement || (ResourceOperationIdempotencyKeyRequirement = {}));
+/**
+ * Longest key accepted, in characters. A key is stored as part of an operation's admission identity, which also carries
+ * the operation name, inside a 255-character column; 200 leaves room for that prefix. A UUID is 36.
+ */
+export const IDEMPOTENCY_KEY_MAX_LENGTH = 200;
+/** Why the framework refused a request's `Idempotency-Key`, carried as the client-branchable `error.code` of a 400. */
+export var IdempotencyKeyRefusalCode;
+(function (IdempotencyKeyRefusalCode) {
+    /** The operation requires the header and the request did not send one. */
+    IdempotencyKeyRefusalCode["REQUIRED"] = "idempotency_key_required";
+    /** The header is present but is not a String of 1 to {@link IDEMPOTENCY_KEY_MAX_LENGTH} printable ASCII characters. */
+    IdempotencyKeyRefusalCode["MALFORMED"] = "idempotency_key_malformed";
+    /**
+     * The header was sent to a MUTATION that does not take one. Refused rather than ignored: a caller who sent a key believes
+     * a retry is deduplicated, and silently ignoring it would let that retry run twice. A read-shaped operation ignores an
+     * undeclared key instead, because repeating a read is harmless.
+     */
+    IdempotencyKeyRefusalCode["NOT_ACCEPTED"] = "idempotency_key_not_accepted";
+})(IdempotencyKeyRefusalCode || (IdempotencyKeyRefusalCode = {}));
+/** What one reading of the header found. */
+export var IdempotencyKeyHeaderOutcome;
+(function (IdempotencyKeyHeaderOutcome) {
+    IdempotencyKeyHeaderOutcome["ABSENT"] = "absent";
+    IdempotencyKeyHeaderOutcome["KEY"] = "key";
+    IdempotencyKeyHeaderOutcome["MALFORMED"] = "malformed";
+})(IdempotencyKeyHeaderOutcome || (IdempotencyKeyHeaderOutcome = {}));
+/** The unquoted form some clients send (Stripe's SDKs among them): token characters only, so it cannot hide a list. */
+const BARE_KEY = /^[A-Za-z0-9._~:+/=-]+$/;
+/**
+ * Read one request's `Idempotency-Key` header value.
+ *
+ * Accepts the draft's String form (`"8e03978e-40d5-43e8-bc93-6894a57f9324"`, printable ASCII, `\"` and `\\` the only
+ * escapes) and, for clients that send it unquoted, a bare token. Anything else is MALFORMED, never trimmed into a key:
+ *
+ * - an empty value (the header was sent, so the caller meant something);
+ * - a repeated header, which Node joins with `, ` and which could otherwise be read as one key made of two;
+ * - a control or non-ASCII character, which would reach logs and a stored admission identity;
+ * - a key longer than {@link IDEMPOTENCY_KEY_MAX_LENGTH}.
+ */
+export function parseIdempotencyKeyHeader(raw) {
+    if (raw === undefined)
+        return { outcome: IdempotencyKeyHeaderOutcome.ABSENT };
+    if (typeof raw !== 'string')
+        return { outcome: IdempotencyKeyHeaderOutcome.MALFORMED };
+    const value = raw.trim();
+    if (value.length === 0)
+        return { outcome: IdempotencyKeyHeaderOutcome.MALFORMED };
+    let key = '';
+    if (value.startsWith('"')) {
+        if (value.length < 2 || !value.endsWith('"'))
+            return { outcome: IdempotencyKeyHeaderOutcome.MALFORMED };
+        const body = value.slice(1, -1);
+        for (let index = 0; index < body.length; index += 1) {
+            const character = body[index];
+            const code = character.charCodeAt(0);
+            if (code < 0x20 || code > 0x7e || character === '"')
+                return { outcome: IdempotencyKeyHeaderOutcome.MALFORMED };
+            if (character === '\\') {
+                const escaped = body[index + 1];
+                if (escaped !== '"' && escaped !== '\\')
+                    return { outcome: IdempotencyKeyHeaderOutcome.MALFORMED };
+                key += escaped;
+                index += 1;
+                continue;
+            }
+            key += character;
+        }
+    }
+    else {
+        if (!BARE_KEY.test(value))
+            return { outcome: IdempotencyKeyHeaderOutcome.MALFORMED };
+        key = value;
+    }
+    if (key.length === 0 || key.length > IDEMPOTENCY_KEY_MAX_LENGTH)
+        return { outcome: IdempotencyKeyHeaderOutcome.MALFORMED };
+    return { outcome: IdempotencyKeyHeaderOutcome.KEY, key };
+}
+/** Write a key as the header's String form, the inverse of {@link parseIdempotencyKeyHeader}. */
+export function formatIdempotencyKeyHeader(key) {
+    return `"${key.replace(/[\\"]/g, (character) => `\\${character}`)}"`;
+}
+//# sourceMappingURL=idempotency-key.shared.js.map

package/dist/esm/requests/idempotency-key.shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"idempotency-key.shared.js","sourceRoot":"","sources":["../../../../src/requests/idempotency-key.shared.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The `Idempotency-Key` request header: its vocabulary, its bounds and its one parser (#535).\n *\n * A caller that sends the same key again is asking for the outcome of the FIRST request, not for a second execution. An\n * operation variant declares whether it takes the header ({@link ResourceOperationIdempotencyKeyRequirement}); the\n * framework parses and bounds the value here, refuses a malformed or undeclared one, and hands the key to the operation's\n * implementation, which owns what \"the same request\" means for its effects (a billing mutation, for example, replays the\n * committed change and refuses the same key sent with a different request).\n *\n * Shared by the backend controller that reads the header, the frontend client that writes it and the OpenAPI projection\n * that documents it, so the three cannot disagree about what a key is.\n *\n * spec-cite: draft-ietf-httpapi-idempotency-key-header-07 (2025-10-15), https://datatracker.ietf.org/doc/html/draft-ietf-httpapi-idempotency-key-header\n * — the header name, its String value, and the 400/409/422 outcomes are taken from that draft; the wording here is this\n * repository's own.\n */\n\n/** Whether an operation variant takes the `Idempotency-Key` request header. Absent on a variant: it takes none. */\nexport enum ResourceOperationIdempotencyKeyRequirement {\n  /**\n   * The header is honored when a caller sends it, and a request without it runs unkeyed. For an operation whose effect\n   * converges when repeated (cancelling, resuming), so an unkeyed retry is safe even though it is not deduplicated.\n   */\n  ACCEPTED = 'accepted',\n  /**\n   * A request without the header is refused with 400 before anything runs. For an operation whose repeat is a second,\n   * different effect (adding an add-on twice adds two), where an unkeyed retry is exactly the duplicate the key prevents.\n   */\n  REQUIRED = 'required',\n}\n\n/**\n * Longest key accepted, in characters. A key is stored as part of an operation's admission identity, which also carries\n * the operation name, inside a 255-character column; 200 leaves room for that prefix. A UUID is 36.\n */\nexport const IDEMPOTENCY_KEY_MAX_LENGTH = 200;\n\n/** Why the framework refused a request's `Idempotency-Key`, carried as the client-branchable `error.code` of a 400. */\nexport enum IdempotencyKeyRefusalCode {\n  /** The operation requires the header and the request did not send one. */\n  REQUIRED = 'idempotency_key_required',\n  /** The header is present but is not a String of 1 to {@link IDEMPOTENCY_KEY_MAX_LENGTH} printable ASCII characters. */\n  MALFORMED = 'idempotency_key_malformed',\n  /**\n   * The header was sent to a MUTATION that does not take one. Refused rather than ignored: a caller who sent a key believes\n   * a retry is deduplicated, and silently ignoring it would let that retry run twice. A read-shaped operation ignores an\n   * undeclared key instead, because repeating a read is harmless.\n   */\n  NOT_ACCEPTED = 'idempotency_key_not_accepted',\n}\n\n/** What one reading of the header found. */\nexport enum IdempotencyKeyHeaderOutcome {\n  ABSENT = 'absent',\n  KEY = 'key',\n  MALFORMED = 'malformed',\n}\n\nexport type IdempotencyKeyHeaderParse =\n  | { outcome: IdempotencyKeyHeaderOutcome.ABSENT }\n  | { outcome: IdempotencyKeyHeaderOutcome.KEY; key: string }\n  | { outcome: IdempotencyKeyHeaderOutcome.MALFORMED };\n\n/** The unquoted form some clients send (Stripe's SDKs among them): token characters only, so it cannot hide a list. */\nconst BARE_KEY = /^[A-Za-z0-9._~:+/=-]+$/;\n\n/**\n * Read one request's `Idempotency-Key` header value.\n *\n * Accepts the draft's String form (`\"8e03978e-40d5-43e8-bc93-6894a57f9324\"`, printable ASCII, `\\\"` and `\\\\` the only\n * escapes) and, for clients that send it unquoted, a bare token. Anything else is MALFORMED, never trimmed into a key:\n *\n * - an empty value (the header was sent, so the caller meant something);\n * - a repeated header, which Node joins with `, ` and which could otherwise be read as one key made of two;\n * - a control or non-ASCII character, which would reach logs and a stored admission identity;\n * - a key longer than {@link IDEMPOTENCY_KEY_MAX_LENGTH}.\n */\nexport function parseIdempotencyKeyHeader(raw: string | readonly string[] | undefined): IdempotencyKeyHeaderParse {\n  if (raw === undefined) return { outcome: IdempotencyKeyHeaderOutcome.ABSENT };\n  if (typeof raw !== 'string') return { outcome: IdempotencyKeyHeaderOutcome.MALFORMED };\n  const value = raw.trim();\n  if (value.length === 0) return { outcome: IdempotencyKeyHeaderOutcome.MALFORMED };\n\n  let key = '';\n  if (value.startsWith('\"')) {\n    if (value.length < 2 || !value.endsWith('\"')) return { outcome: IdempotencyKeyHeaderOutcome.MALFORMED };\n    const body = value.slice(1, -1);\n    for (let index = 0; index < body.length; index += 1) {\n      const character = body[index]!;\n      const code = character.charCodeAt(0);\n      if (code < 0x20 || code > 0x7e || character === '\"') return { outcome: IdempotencyKeyHeaderOutcome.MALFORMED };\n      if (character === '\\\\') {\n        const escaped = body[index + 1];\n        if (escaped !== '\"' && escaped !== '\\\\') return { outcome: IdempotencyKeyHeaderOutcome.MALFORMED };\n        key += escaped;\n        index += 1;\n        continue;\n      }\n      key += character;\n    }\n  } else {\n    if (!BARE_KEY.test(value)) return { outcome: IdempotencyKeyHeaderOutcome.MALFORMED };\n    key = value;\n  }\n  if (key.length === 0 || key.length > IDEMPOTENCY_KEY_MAX_LENGTH) return { outcome: IdempotencyKeyHeaderOutcome.MALFORMED };\n  return { outcome: IdempotencyKeyHeaderOutcome.KEY, key };\n}\n\n/** Write a key as the header's String form, the inverse of {@link parseIdempotencyKeyHeader}. */\nexport function formatIdempotencyKeyHeader(key: string): string {\n  return `\"${key.replace(/[\\\\\"]/g, (character) => `\\\\${character}`)}\"`;\n}\n"]}

package/dist/esm/requests/manual-controllers-routes-documentation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"manual-controllers-routes-documentation.d.ts","sourceRoot":"","sources":["../../../src/requests/manual-controllers-routes-documentation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AAE5E;;;;;;;;;;;GAWG;AACH,oBAAY,0BAA0B;IACpC,gGAAgG;IAChG,cAAc,mBAAmB;IACjC,wGAAwG;IACxG,iBAAiB,qBAAqB;IACtC,2GAA2G;IAC3G,kBAAkB,sBAAsB;IACxC,uFAAuF;IACvF,gBAAgB,oBAAoB;IACpC,yEAAyE;IACzE,aAAa,iBAAiB;IAC9B,kFAAkF;IAClF,mBAAmB,uBAAuB;CAC3C;AAED;;;GAGG;AACH,oBAAY,mCAAmC;IAC7C,2GAA2G;IAC3G,MAAM,WAAW;IACjB,kEAAkE;IAClE,iBAAiB,sBAAsB;IACvC,0EAA0E;IAC1E,aAAa,kBAAkB;IAC/B,kFAAkF;IAClF,0BAA0B,+BAA+B;CAC1D;AAED,oEAAoE;AACpE,oBAAY,gCAAgC;IAC1C,SAAS,cAAc;IACvB,QAAQ,aAAa;CACtB;AAED,8FAA8F;AAC9F,MAAM,WAAW,2CAA2C;IAC1D,QAAQ,CAAC,WAAW,EAAE,gCAAgC,CAAC,SAAS,CAAC;IACjE,QAAQ,CAAC,KAAK,EAAE,0BAA0B,CAAC;IAC3C;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,SAAS,UAAU,EAAE,CAAC;IACxC,kGAAkG;IAClG,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,uGAAuG;IACvG,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,cAAc,EAAE,mCAAmC,CAAC;IAC7D,yDAAyD;IACzD,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IACvC;;;OAGG;IACH,QAAQ,CAAC,aAAa,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7E;AAED;;;;;;GAMG;AACH,MAAM,WAAW,0CAA0C;IACzD,QAAQ,CAAC,WAAW,EAAE,gCAAgC,CAAC,QAAQ,CAAC;IAChE,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,MAAM,kCAAkC,GAC1C,2CAA2C,GAC3C,0CAA0C,CAAC;AAoB/C,gGAAgG;AAChG,eAAO,MAAM,0CAA0C,EAAE,MAAM,CAAC,0BAA0B,EAAE,MAAM,CAuBjG,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,qCAAqC,EAAE,MAAM,CAAC,wBAAwB,EAAE,kCAAkC,CAssCtH,CAAC"}
+{"version":3,"file":"manual-controllers-routes-documentation.d.ts","sourceRoot":"","sources":["../../../../src/requests/manual-controllers-routes-documentation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AAE5E;;;;;;;;;;;GAWG;AACH,oBAAY,0BAA0B;IACpC,gGAAgG;IAChG,cAAc,mBAAmB;IACjC,wGAAwG;IACxG,iBAAiB,qBAAqB;IACtC,2GAA2G;IAC3G,kBAAkB,sBAAsB;IACxC,uFAAuF;IACvF,gBAAgB,oBAAoB;IACpC,yEAAyE;IACzE,aAAa,iBAAiB;IAC9B,kFAAkF;IAClF,mBAAmB,uBAAuB;CAC3C;AAED;;;GAGG;AACH,oBAAY,mCAAmC;IAC7C,2GAA2G;IAC3G,MAAM,WAAW;IACjB,kEAAkE;IAClE,iBAAiB,sBAAsB;IACvC,0EAA0E;IAC1E,aAAa,kBAAkB;IAC/B,kFAAkF;IAClF,0BAA0B,+BAA+B;CAC1D;AAED,oEAAoE;AACpE,oBAAY,gCAAgC;IAC1C,SAAS,cAAc;IACvB,QAAQ,aAAa;CACtB;AAED,8FAA8F;AAC9F,MAAM,WAAW,2CAA2C;IAC1D,QAAQ,CAAC,WAAW,EAAE,gCAAgC,CAAC,SAAS,CAAC;IACjE,QAAQ,CAAC,KAAK,EAAE,0BAA0B,CAAC;IAC3C;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,SAAS,UAAU,EAAE,CAAC;IACxC,kGAAkG;IAClG,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,uGAAuG;IACvG,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,cAAc,EAAE,mCAAmC,CAAC;IAC7D,yDAAyD;IACzD,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IACvC;;;OAGG;IACH,QAAQ,CAAC,aAAa,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7E;AAED;;;;;;GAMG;AACH,MAAM,WAAW,0CAA0C;IACzD,QAAQ,CAAC,WAAW,EAAE,gCAAgC,CAAC,QAAQ,CAAC;IAChE,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,MAAM,kCAAkC,GAC1C,2CAA2C,GAC3C,0CAA0C,CAAC;AAoB/C,gGAAgG;AAChG,eAAO,MAAM,0CAA0C,EAAE,MAAM,CAAC,0BAA0B,EAAE,MAAM,CAuBjG,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,qCAAqC,EAAE,MAAM,CAAC,wBAAwB,EAAE,kCAAkC,CA85CtH,CAAC"}

package/dist/esm/requests/manual-controllers-routes-documentation.js

@@ -227,8 +227,8 @@ export const MANUAL_CONTROLLER_ROUTE_DOCUMENTATION = {
         methods: [HttpMethod.POST],
         summary: 'Register a new account',
         description: 'Creates an account from the sign-up details the application asks for. Whether the new account can sign in immediately, '
-            + 'must verify its email address first, or must complete organization onboarding depends on how this application is '
-            + 'configured; the answer says which of those applies.',
+            + 'must verify its email address first, must enroll a second factor before it can sign in, or must complete organization '
+            + 'onboarding depends on how this application is configured; the answer says which of those applies.',
         authentication: PUBLIC,
         authenticationSummary: NO_CREDENTIAL,
         successStatus: ok('The account, and what it must do before it can sign in.'),
@@ -282,11 +282,29 @@ export const MANUAL_CONTROLLER_ROUTE_DOCUMENTATION = {
         group: AUTH,
         methods: [HttpMethod.POST],
         summary: 'Complete organization onboarding',
-        description: 'For applications that defer organization creation past sign-up: creates the caller\'s organization and finishes putting '
-            + 'them into it. Only meaningful for an account the register step left in that state.',
-        authentication: BEARER,
-        authenticationSummary: BEARER_CREDENTIAL,
-        successStatus: ok('The organization exists and the caller belongs to it.'),
+        description: 'For applications that name an account\'s organization at onboarding: creates the organization and makes the account '
+            + 'its owner, on an authentication session parked at `ONBOARDING_PENDING` — by registration, by email verification or '
+            + 'enrollment, or by a sign-in answered `nextStep: onboarding` because the account still owes its organization. It '
+            + 'signs the account in when nothing else is owed; when another onboarding obligation remains (the person\'s names, for '
+            + 'a user type that collects them at onboarding), the session stays parked and the response names what is still owed. '
+            + 'A sign-in response carries the access token; the refresh token is set only as the HttpOnly refresh cookie.',
+        authentication: PUBLIC,
+        authenticationSummary: 'No credential. The parked session id in the body is what authorizes the completion, and it is consumed by it.',
+        successStatus: ok('The organization exists and the account owns it; the account is signed in unless another obligation remains.'),
+    },
+    [ManualControllerRouteKey.AUTH_COMPLETE_PROFILE_ONBOARDING]: {
+        publication: ManualControllerRoutePublication.PUBLISHED,
+        group: AUTH,
+        methods: [HttpMethod.POST],
+        summary: 'Complete profile onboarding',
+        description: 'For user types that collect a person\'s first and last name at onboarding rather than on the sign-up form: writes the '
+            + 'account\'s profile with those names, on an authentication session parked at `ONBOARDING_PENDING` that owes them. It '
+            + 'signs the account in when nothing else is owed; when the organization is still owed, the session stays parked and '
+            + 'the response names what remains. A sign-in response carries the access token; the refresh token is set only as the '
+            + 'HttpOnly refresh cookie.',
+        authentication: PUBLIC,
+        authenticationSummary: 'No credential. The parked session id in the body is what authorizes the completion.',
+        successStatus: ok('The profile carries the names; the account is signed in unless another obligation remains.'),
     },
     // ─── Invitations ─────────────────────────────────────────────────────────────────────────────
     [ManualControllerRouteKey.AUTH_INVITATION_INFO]: {
@@ -306,12 +324,13 @@ export const MANUAL_CONTROLLER_ROUTE_DOCUMENTATION = {
         group: AUTH,
         methods: [HttpMethod.POST],
         summary: 'Accept an invitation with its token',
-        description: 'Consumes an invitation token, joins the invited organization and signs the person in. For somebody arriving from the '
-            + 'invitation email with no session. A signed-in user acting on their own pending invitations uses **Accept one of my '
+        description: 'Consumes an invitation token and joins the invited organization. It then signs the person in, emails them a sign-in '
+            + 'link when they chose one, or, for an existing account whose policy does not allow signing in from an emailed link, '
+            + 'answers `nextStep: sign_in_required` and signs nobody in. For somebody arriving from the invitation email with no session. A signed-in user acting on their own pending invitations uses **Accept one of my '
             + 'invitations** instead, which needs no token.',
         authentication: PUBLIC,
         authenticationSummary: 'No credential. The single-use invitation token is what authorizes the join.',
-        successStatus: ok('Membership is created and the caller is signed in.'),
+        successStatus: ok('Membership is created; the caller is signed in, sent a sign-in link, or told to sign in.'),
     },
     [ManualControllerRouteKey.AUTH_REJECT_INVITATION]: {
         publication: ManualControllerRoutePublication.PUBLISHED,
@@ -506,8 +525,13 @@ export const MANUAL_CONTROLLER_ROUTE_DOCUMENTATION = {
         group: AUTH,
         methods: [HttpMethod.POST],
         summary: 'Begin passkey authentication',
-        description: 'Returns the WebAuthn request options — challenge and allowed credentials — to hand to '
-            + '`navigator.credentials.get()` when signing in with a passkey.',
+        description: 'Returns `{ sessionId, options, expiresInSeconds }`: the WebAuthn request options to hand to '
+            + '`navigator.credentials.get()`, the authentication session their challenge is bound to, and how long that '
+            + 'challenge can still be redeemed — a waiting autofill request should be restarted before then. Without a `sessionId` it opens a sign-in '
+            + 'before any email is known (passkey autofill, or a sign-in-with-a-passkey button). For a sign-in the '
+            + 'options list no credentials, so the device offers every account the person holds for this site and '
+            + 'the answer is the same whatever email was entered; for a second factor they list the signed-in '
+            + 'account\'s own passkeys.',
         authentication: PUBLIC,
         authenticationSummary: NO_CREDENTIAL,
         successStatus: ok('WebAuthn request options for the browser.'),
@@ -517,7 +541,9 @@ export const MANUAL_CONTROLLER_ROUTE_DOCUMENTATION = {
         group: AUTH,
         methods: [HttpMethod.POST],
         summary: 'Complete passkey authentication',
-        description: 'Presents the assertion the authenticator produced; on success the answer carries the access token.',
+        description: 'Presents the assertion the authenticator produced, with the `sessionId` its options were issued for. '
+            + 'The account is the one the passkey belongs to, whatever email was entered. On success the answer '
+            + 'carries the access token; `passkeyCredentialUnknown` marks a passkey this application no longer holds.',
         authentication: PUBLIC,
         authenticationSummary: 'No credential. The WebAuthn assertion is the proof.',
         successStatus: ok('An access token and the caller\'s session.'),
@@ -609,13 +635,51 @@ export const MANUAL_CONTROLLER_ROUTE_DOCUMENTATION = {
         authenticationSummary: 'A bearer access token plus a fresh re-authentication token.',
         successStatus: ok('The identity is unlinked.'),
     },
+    [ManualControllerRouteKey.GOVERNED_DOCUMENT_ACCEPTANCES_OWED]: {
+        publication: ManualControllerRoutePublication.PUBLISHED,
+        group: RUNTIME,
+        methods: [HttpMethod.GET],
+        summary: 'List the documents I owe an acceptance of',
+        description: 'The governed documents in force that the caller has never accepted, or that changed materially since they last '
+            + 'did — each with every in-force variant (one per locale and jurisdiction). Empty for an application that asks '
+            + 'for no acceptance.',
+        authentication: BEARER,
+        authenticationSummary: BEARER_CREDENTIAL,
+        successStatus: ok('The documents the caller owes an acceptance of.'),
+    },
+    [ManualControllerRouteKey.GOVERNED_DOCUMENT_ACCEPTANCES_ACCEPT]: {
+        publication: ManualControllerRoutePublication.PUBLISHED,
+        group: RUNTIME,
+        methods: [HttpMethod.POST],
+        summary: 'Accept governed documents',
+        description: 'Records that the caller accepted the named in-force releases. Only release IDS are sent: which version, which '
+            + 'document and how the application asked are all read from the application\'s own configuration, so a caller '
+            + 'cannot choose the terms they are recorded as having agreed to. An id naming nothing in force is ignored.',
+        authentication: BEARER,
+        authenticationSummary: BEARER_CREDENTIAL,
+        successStatus: ok('The acceptances are recorded; the response lists what is still owed.'),
+    },
+    [ManualControllerRouteKey.GOVERNED_DOCUMENT_NOTICE_DELIVERED]: {
+        publication: ManualControllerRoutePublication.PUBLISHED,
+        group: RUNTIME,
+        methods: [HttpMethod.POST],
+        summary: 'Record that a governed document was delivered to me',
+        description: 'Records that the caller was shown the named governed document. Only the document REF is sent: the exact release '
+            + 'version in force is resolved from the application\'s own configuration, never from the request. A document '
+            + 'whose in-force release does not permit recording a delivery is silently a no-op.',
+        authentication: BEARER,
+        authenticationSummary: BEARER_CREDENTIAL,
+        successStatus: ok('The delivery is recorded, or silently skipped when nothing in force permits it.'),
+    },
     [ManualControllerRouteKey.AUTH_REAUTH]: {
         publication: ManualControllerRoutePublication.PUBLISHED,
         group: AUTH,
         methods: [HttpMethod.POST],
         summary: 'Re-authenticate for a sensitive operation',
         description: 'Proves the person at the keyboard is still the account holder, and returns the single-use step-up token that sensitive '
-            + 'operations require in their step-up header. This is the endpoint those operations point at.',
+            + 'operations require in their step-up header. This is the endpoint those operations point at. `purpose` says what the '
+            + 'proof is for: `step_up` (the default) must use a factor the account\'s step-up policy accepts; `bind_authenticator`, '
+            + 'asked for when adding a way to sign in, accepts any factor the account holds and is accepted only by those doors.',
         authentication: BEARER,
         authenticationSummary: BEARER_CREDENTIAL,
         successStatus: ok('A single-use step-up token.'),
@@ -631,6 +695,44 @@ export const MANUAL_CONTROLLER_ROUTE_DOCUMENTATION = {
         authenticationSummary: BEARER_CREDENTIAL,
         successStatus: ok('WebAuthn request options for the step-up.'),
     },
+    [ManualControllerRouteKey.AUTH_REAUTH_METHODS]: {
+        publication: ManualControllerRoutePublication.PUBLISHED,
+        group: AUTH,
+        methods: [HttpMethod.GET],
+        summary: 'List the factors that can re-authenticate you',
+        description: 'Which of the signed-in person\'s own factors can produce a re-authentication proof for the given `purpose`, strongest '
+            + 'first. For `step_up`, only factors the account\'s step-up policy accepts are listed; for `bind_authenticator` (adding a '
+            + 'way to sign in), every factor the account holds is. Also lists the linked identities whose provider can '
+            + 're-authenticate the person (`identityLinks`). Both empty means the account must add an accepted factor first.',
+        authentication: BEARER,
+        authenticationSummary: BEARER_CREDENTIAL,
+        successStatus: ok('The factors, strongest first, and the re-provable linked identities.'),
+    },
+    [ManualControllerRouteKey.AUTH_REAUTH_FEDERATED_AUTHORIZE]: {
+        publication: ManualControllerRoutePublication.PUBLISHED,
+        group: AUTH,
+        methods: [HttpMethod.POST],
+        summary: 'Re-authenticate through a linked identity provider',
+        description: 'Starts a re-authentication at the identity provider behind one of the signed-in person\'s own linked accounts, for the '
+            + 'given `purpose`. Answers the provider URL to open (in a popup). The provider is asked to sign the person in afresh '
+            + '(OIDC `prompt=login` + `max_age=0`, SAML `ForceAuthn`), and the proof is minted only if its signed answer (the ID '
+            + 'token\'s `auth_time`, or the assertion\'s `AuthnInstant`) shows a sign-in newer than this request. Refused for a link whose '
+            + 'provider or connection has not enabled re-authentication.',
+        authentication: BEARER,
+        authenticationSummary: BEARER_CREDENTIAL,
+        successStatus: ok('The identity provider URL to open.'),
+    },
+    [ManualControllerRouteKey.AUTH_REAUTH_FEDERATED_EXCHANGE]: {
+        publication: ManualControllerRoutePublication.PUBLISHED,
+        group: AUTH,
+        methods: [HttpMethod.POST],
+        summary: 'Redeem a federated re-authentication',
+        description: 'Exchanges the one-time code a federated re-authentication returned for its single-use re-authentication token. The code '
+            + 'is redeemable only by the account it was minted for, with that account\'s own bearer.',
+        authentication: BEARER,
+        authenticationSummary: BEARER_CREDENTIAL,
+        successStatus: ok('A single-use re-authentication token.'),
+    },
     // ─── Signing in through somebody else's identity provider ────────────────────────────────────
     [ManualControllerRouteKey.AUTH_OAUTH2_AUTHORIZE]: {
         publication: ManualControllerRoutePublication.PUBLISHED,
@@ -660,12 +762,14 @@ export const MANUAL_CONTROLLER_ROUTE_DOCUMENTATION = {
         publication: ManualControllerRoutePublication.PUBLISHED,
         group: AUTH,
         methods: [HttpMethod.POST],
-        summary: 'Exchange a one-time code for tokens',
+        summary: 'Exchange a one-time code for tokens or the onboarding step',
         description: 'Turns the single-use code a redirect flow handed back into the access token and session. Single-use: the code is '
-            + 'consumed, so it cannot be replayed if it leaks into a browser history or a referrer header.',
+            + 'consumed, so it cannot be replayed if it leaks into a browser history or a referrer header. When the account '
+            + 'still has to name its organization, the answer is instead the onboarding step and the session to complete it '
+            + 'with — no token and no session cookie until the organization is named.',
         authentication: PUBLIC,
         authenticationSummary: 'No credential. The single-use code is the proof.',
-        successStatus: ok('An access token and the caller\'s session.'),
+        successStatus: ok('An access token and the caller\'s session, or the organization-onboarding step still owed.'),
     },
     [ManualControllerRouteKey.AUTH_ENTERPRISE_SSO_AUTHORIZE]: {
         publication: ManualControllerRoutePublication.PUBLISHED,
@@ -1050,6 +1154,36 @@ export const MANUAL_CONTROLLER_ROUTE_DOCUMENTATION = {
         authenticationSummary: BEARER_CREDENTIAL,
         successStatus: ok('The access token, with its expiry and granted scopes when the vendor stated them.'),
     },
+    [ManualControllerRouteKey.PROVIDER_OPERATION_EXECUTE]: {
+        publication: ManualControllerRoutePublication.PUBLISHED,
+        group: CONNECTIONS,
+        methods: [HttpMethod.POST],
+        summary: 'Run a provider operation this application lets your browser trigger',
+        description: 'Executes one operation of a connected third-party provider on the server and returns its parsed output. The '
+            + 'credential never reaches the browser: the body names whose account to spend (`connection`, defaulting to the '
+            + 'application\u2019s own), an optional catalogue `domain`, and the operation `input`. Only operations the '
+            + 'application declared browser-reachable can run, for the connections and roles it declared; anything else '
+            + 'answers 403 and the refusal is recorded. Every executed call is recorded too, successful or not, against the '
+            + 'person who asked.',
+        authentication: BEARER,
+        authenticationSummary: BEARER_CREDENTIAL,
+        successStatus: ok('The provider\u2019s HTTP status and the operation\u2019s output, parsed through its declared schema.'),
+    },
+    [ManualControllerRouteKey.PROVIDER_OPERATION_INPUT_OPTIONS]: {
+        publication: ManualControllerRoutePublication.PUBLISHED,
+        group: CONNECTIONS,
+        methods: [HttpMethod.POST],
+        summary: 'List the choices for one input of a provider operation',
+        description: 'Lists the values a person may pick for one input of a browser-reachable provider operation \u2014 a workspace, a '
+            + 'project \u2014 by running the input\u2019s declared options operation on the server, through the connection named in '
+            + 'the body. The list is exactly what that account can see, and the credential never reaches the browser. Both the '
+            + 'operation and its options operation must be declared browser-reachable for that connection; otherwise the answer is '
+            + '403 and the refusal is recorded. A choice the list depends on must be passed in `input`: without it the answer is '
+            + '400 naming it, rather than an empty list.',
+        authentication: BEARER,
+        authenticationSummary: BEARER_CREDENTIAL,
+        successStatus: ok('The options operation that answered, and each choice as a value and the vendor\u2019s own label.'),
+    },
     // ─── Agent interfaces ────────────────────────────────────────────────────────────────────────
     [ManualControllerRouteKey.MCP_ENDPOINT]: {
         publication: ManualControllerRoutePublication.PUBLISHED,
@@ -1138,6 +1272,17 @@ export const MANUAL_CONTROLLER_ROUTE_DOCUMENTATION = {
         authenticationSummary: BEARER_CREDENTIAL,
         successStatus: { code: '201', meaning: 'The share link and when it expires.' },
     },
+    [ManualControllerRouteKey.FILES_SHARES_REVOKE]: {
+        publication: ManualControllerRoutePublication.PUBLISHED,
+        group: FILES,
+        methods: [HttpMethod.DELETE],
+        summary: 'Revoke every share link of a stored file',
+        description: 'Stops sharing this file: every link minted for it that is still live stops working at once, whoever minted it. '
+            + 'Anyone who may create a share link for the file may revoke them. Idempotent: with no live link it answers a count of zero.',
+        authentication: BEARER,
+        authenticationSummary: BEARER_CREDENTIAL,
+        successStatus: ok('How many live share links were revoked.'),
+    },
     [ManualControllerRouteKey.FILES_UPLOAD_GRANT_STATUS]: {
         publication: ManualControllerRoutePublication.PUBLISHED,
         group: FILES,
@@ -1196,6 +1341,62 @@ export const MANUAL_CONTROLLER_ROUTE_DOCUMENTATION = {
         authenticationSummary: BEARER_CREDENTIAL,
         successStatus: ok('The chart\'s data series.'),
     },
+    [ManualControllerRouteKey.SUBJECT_ERASURE_LANE_EVIDENCE]: {
+        publication: ManualControllerRoutePublication.PUBLISHED,
+        group: RUNTIME,
+        methods: [HttpMethod.GET],
+        summary: "Summarize this application's subject-erasure lane over a window",
+        description: 'Counts, for a closed window, what the erasure lane did: how many requests arrived and who raised each, how many were '
+            + 'withdrawn, how many reached a terminal state, and how many of those are missing the requester, justification or outcome '
+            + 'their own record promises. It also reports whether the withdrawal door is reachable to a subject and what schedule drives '
+            + 'execution, both read from the lane the application declared. It returns NO row and NO identifier — an evidence reader '
+            + 'proving the lane works must not be handed every person who asked to be erased in order to count them. An application that '
+            + 'declares no erasure lane is told so explicitly, because a lane with no activity and no lane at all are the same zeroes.',
+        authentication: BEARER,
+        authenticationSummary: BEARER_CREDENTIAL,
+        successStatus: ok('The lane summary, or a statement that no lane is declared.'),
+    },
+    [ManualControllerRouteKey.PROVIDER_CALL_EVIDENCE]: {
+        publication: ManualControllerRoutePublication.PUBLISHED,
+        group: RUNTIME,
+        methods: [HttpMethod.GET],
+        summary: 'Count the model-provider calls this application made over a window',
+        description: 'Counts, for a closed window, every call the application made to a model provider: grouped by provider, model, kind of call '
+            + 'and outcome, with the tokens each group consumed. It also counts the records that are incomplete (no provider, no model, no '
+            + 'reported usage) separately, so a gap is visible rather than folded into the total. It returns NO row: the question is about '
+            + 'the population of calls, and a record names an agent and an instant an evidence reader has no need to hold.',
+        authentication: BEARER,
+        authenticationSummary: BEARER_CREDENTIAL,
+        successStatus: ok('The provider-call summary for the window.'),
+    },
+    [ManualControllerRouteKey.USAGE_FLUSH_EVIDENCE]: {
+        publication: ManualControllerRoutePublication.PUBLISHED,
+        group: RUNTIME,
+        methods: [HttpMethod.GET],
+        summary: 'Count where the metered-usage rows stand with respect to the provider flush',
+        description: 'Counts every usage row by flush state (pending, reported, unreportable), the unreportable rows by reason, and the '
+            + 'contradictions that must never exist: an unreportable row with no reason, one with no decision instant, and one also '
+            + 'marked reported. The window adds how many rows were decided unreportable inside it. It returns NO row: a usage row names '
+            + 'a customer and a quantity, which an evidence reader has no need to hold. An application with billing off measures no store, '
+            + 'and says so.',
+        authentication: BEARER,
+        authenticationSummary: BEARER_CREDENTIAL,
+        successStatus: ok('The usage flush summary.'),
+    },
+    [ManualControllerRouteKey.SCHEDULED_EVIDENCE_COVERAGE]: {
+        publication: ManualControllerRoutePublication.PUBLISHED,
+        group: RUNTIME,
+        methods: [HttpMethod.POST],
+        summary: 'Assess whether a scheduled run happened as often as it was scheduled to',
+        description: 'Compares the runs this application retained, and its live job history, against the schedule that was IN FORCE across the period — '
+            + 'supplied by the caller as historical segments, each naming the commit that set it. Reports coverage, missing occurrences, duplicate '
+            + 'runs, outcomes, unavailable results, deferral and timeliness separately, because a run that happened and failed, one that happened '
+            + 'late, and one that never happened are different findings. POST because the schedule basis is a body: the current cron cannot stand in '
+            + 'for what the schedule WAS, so a caller that supplies none gets a refusal rather than an assessment against today.',
+        authentication: BEARER,
+        authenticationSummary: BEARER_CREDENTIAL,
+        successStatus: ok('The coverage assessment for one scheduled target over the period.'),
+    },
     [ManualControllerRouteKey.FLOWS_ACTORS_FRONTEND_INFO]: {
         publication: ManualControllerRoutePublication.PUBLISHED,
         group: RUNTIME,