@oxy.so/contracts 4.17.0 → 4.21.0

package/dist/types/applicationRoles.d.ts

@@ -0,0 +1,438 @@
+/**
+ * Application roles — the wire contract for permissions an APPLICATION declares
+ * about its own users, and for the grants that give them to Oxy users.
+ *
+ * Oxy decides who holds an app's operator powers (who may run Mercaria's
+ * payments desk, moderate GoWay, administer Homiio), so no app keeps an
+ * allow-list of Oxy user ids in its environment. The app declares a closed
+ * vocabulary of keys, its owners grant them to people, and the app's backend
+ * asks Oxy which of them the human behind a request holds
+ * (`GET /applications/:appId/roles/me`, read through `@oxy.so/core/server`).
+ *
+ * ## Why an application key can never collide with an Oxy permission
+ *
+ * Every permission Oxy itself checks (`app:update`, `apps:create`,
+ * `credentials:rotate`, every scope) is spelled with a COLON. An application key
+ * is dot-separated lowercase segments and cannot contain one, so the two
+ * vocabularies are disjoint by syntax, not by convention. They are also stored
+ * apart (scoped to one application id) and no Oxy gate ever reads an
+ * application key. A key means something only to the application that declared
+ * it.
+ *
+ * The pattern is exported as a SOURCE string because the API renders the same
+ * text into a Postgres CHECK; JavaScript's `RegExp` and Postgres' ARE agree on
+ * everything it uses (anchors, classes, a capturing group, a bounded repeat).
+ *
+ * Platform-agnostic — zod only, no react/react-native/expo.
+ */
+import { z } from 'zod';
+/**
+ * Two to four dot-separated segments, each a lowercase letter followed by
+ * lowercase letters, digits or underscores: `payments.operate`,
+ * `catalog.review.publish`. At least two segments so a key always names an
+ * area and an action; never a colon (see the header).
+ */
+export declare const APPLICATION_PERMISSION_KEY_PATTERN_SOURCE = "^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*){1,3}$";
+export declare const APPLICATION_PERMISSION_KEY_PATTERN: RegExp;
+export declare const APPLICATION_PERMISSION_KEY_MAX_LENGTH = 64;
+export declare const APPLICATION_PERMISSION_DESCRIPTION_MAX_LENGTH = 280;
+/** How many live keys one application may declare. Operator powers are few. */
+export declare const APPLICATION_PERMISSIONS_MAX_DECLARED = 64;
+export declare const APPLICATION_ROLE_REASON_MAX_LENGTH = 500;
+export declare const APPLICATION_ROLE_GRANTS_PAGE_DEFAULT = 50;
+export declare const APPLICATION_ROLE_GRANTS_PAGE_MAX = 200;
+/**
+ * The `error` codes the application-roles routes answer beyond the generic
+ * ones (`BAD_REQUEST`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`). Renaming one
+ * is a breaking change.
+ */
+export declare const APPLICATION_ROLE_ERROR_CODES: {
+    /** 403: a grant naming yourself on an application you do not own outright. */
+    readonly selfGrantForbidden: "SELF_GRANT_FORBIDDEN";
+    /** 422: the key is not a live declared permission of this application. */
+    readonly unknownPermission: "UNKNOWN_PERMISSION";
+    /** 422: the grantee is not a person (an organization, project, bot or channel). */
+    readonly granteeNotAPerson: "GRANTEE_NOT_A_PERSON";
+    /** 409: the grantee already holds the key; `details.grantId` names the live grant. */
+    readonly alreadyGranted: "ALREADY_GRANTED";
+    /** 409: the grant was already revoked. */
+    readonly alreadyRevoked: "ALREADY_REVOKED";
+    /** 403: the bearer's session belongs to a DIFFERENT application. */
+    readonly sessionApplicationMismatch: "SESSION_APPLICATION_MISMATCH";
+};
+export type ApplicationRoleErrorCode = (typeof APPLICATION_ROLE_ERROR_CODES)[keyof typeof APPLICATION_ROLE_ERROR_CODES];
+/** Whether `value` is a well-formed application permission key. */
+export declare function isApplicationPermissionKey(value: unknown): value is string;
+export declare const applicationPermissionKeySchema: z.ZodString;
+/** One key as the application's owners declare it. */
+export declare const applicationPermissionDeclarationSchema: z.ZodObject<{
+    key: z.ZodString;
+    description: z.ZodEffects<z.ZodString, string, string>;
+}, "strict", z.ZodTypeAny, {
+    description: string;
+    key: string;
+}, {
+    description: string;
+    key: string;
+}>;
+/**
+ * `PUT /applications/:appId/roles/permissions` — the WHOLE vocabulary.
+ *
+ * Declarative: a key present here and not live is added, a live key absent
+ * here is retired (and every grant of it revoked), a live key present here
+ * keeps its identity and takes the new description. Sending the same body twice
+ * changes nothing.
+ */
+export declare const declareApplicationPermissionsRequestSchema: z.ZodEffects<z.ZodObject<{
+    permissions: z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        description: z.ZodEffects<z.ZodString, string, string>;
+    }, "strict", z.ZodTypeAny, {
+        description: string;
+        key: string;
+    }, {
+        description: string;
+        key: string;
+    }>, "many">;
+}, "strict", z.ZodTypeAny, {
+    permissions: {
+        description: string;
+        key: string;
+    }[];
+}, {
+    permissions: {
+        description: string;
+        key: string;
+    }[];
+}>, {
+    permissions: {
+        description: string;
+        key: string;
+    }[];
+}, {
+    permissions: {
+        description: string;
+        key: string;
+    }[];
+}>;
+/** A declared key. Retired keys are history: they confer nothing. */
+export declare const applicationPermissionSchema: z.ZodObject<{
+    key: z.ZodString;
+    description: z.ZodString;
+    declaredAt: z.ZodString;
+    declaredByUserId: z.ZodNullable<z.ZodString>;
+    retiredAt: z.ZodNullable<z.ZodString>;
+    retiredByUserId: z.ZodNullable<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    description: string;
+    key: string;
+    declaredAt: string;
+    declaredByUserId: string | null;
+    retiredAt: string | null;
+    retiredByUserId: string | null;
+}, {
+    description: string;
+    key: string;
+    declaredAt: string;
+    declaredByUserId: string | null;
+    retiredAt: string | null;
+    retiredByUserId: string | null;
+}>;
+export declare const applicationPermissionListSchema: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        description: z.ZodString;
+        declaredAt: z.ZodString;
+        declaredByUserId: z.ZodNullable<z.ZodString>;
+        retiredAt: z.ZodNullable<z.ZodString>;
+        retiredByUserId: z.ZodNullable<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        description: string;
+        key: string;
+        declaredAt: string;
+        declaredByUserId: string | null;
+        retiredAt: string | null;
+        retiredByUserId: string | null;
+    }, {
+        description: string;
+        key: string;
+        declaredAt: string;
+        declaredByUserId: string | null;
+        retiredAt: string | null;
+        retiredByUserId: string | null;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    items: {
+        description: string;
+        key: string;
+        declaredAt: string;
+        declaredByUserId: string | null;
+        retiredAt: string | null;
+        retiredByUserId: string | null;
+    }[];
+}, {
+    items: {
+        description: string;
+        key: string;
+        declaredAt: string;
+        declaredByUserId: string | null;
+        retiredAt: string | null;
+        retiredByUserId: string | null;
+    }[];
+}>;
+export declare const declareApplicationPermissionsResponseSchema: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        description: z.ZodString;
+        declaredAt: z.ZodString;
+        declaredByUserId: z.ZodNullable<z.ZodString>;
+        retiredAt: z.ZodNullable<z.ZodString>;
+        retiredByUserId: z.ZodNullable<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        description: string;
+        key: string;
+        declaredAt: string;
+        declaredByUserId: string | null;
+        retiredAt: string | null;
+        retiredByUserId: string | null;
+    }, {
+        description: string;
+        key: string;
+        declaredAt: string;
+        declaredByUserId: string | null;
+        retiredAt: string | null;
+        retiredByUserId: string | null;
+    }>, "many">;
+} & {
+    /** Keys that became live with this declaration. */
+    added: z.ZodArray<z.ZodString, "many">;
+    /** Keys this declaration retired. */
+    retired: z.ZodArray<z.ZodString, "many">;
+    /** Live keys whose description changed. */
+    described: z.ZodArray<z.ZodString, "many">;
+    /** Live grants revoked because their key was retired. */
+    revokedGrants: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    items: {
+        description: string;
+        key: string;
+        declaredAt: string;
+        declaredByUserId: string | null;
+        retiredAt: string | null;
+        retiredByUserId: string | null;
+    }[];
+    added: string[];
+    retired: string[];
+    described: string[];
+    revokedGrants: number;
+}, {
+    items: {
+        description: string;
+        key: string;
+        declaredAt: string;
+        declaredByUserId: string | null;
+        retiredAt: string | null;
+        retiredByUserId: string | null;
+    }[];
+    added: string[];
+    retired: string[];
+    described: string[];
+    revokedGrants: number;
+}>;
+/** One grant of one key to one Oxy user. Revocation is a stamp, never a delete. */
+export declare const applicationRoleGrantSchema: z.ZodObject<{
+    id: z.ZodString;
+    applicationId: z.ZodString;
+    permission: z.ZodString;
+    userId: z.ZodString;
+    /** The grantee's handle, for display. */
+    username: z.ZodNullable<z.ZodString>;
+    /** The HUMAN who granted it; null once that account was erased. */
+    grantedByUserId: z.ZodNullable<z.ZodString>;
+    grantedAt: z.ZodString;
+    grantReason: z.ZodNullable<z.ZodString>;
+    revokedAt: z.ZodNullable<z.ZodString>;
+    revokedByUserId: z.ZodNullable<z.ZodString>;
+    revokeReason: z.ZodNullable<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    username: string | null;
+    id: string;
+    applicationId: string;
+    revokedAt: string | null;
+    userId: string;
+    permission: string;
+    grantedByUserId: string | null;
+    grantedAt: string;
+    grantReason: string | null;
+    revokedByUserId: string | null;
+    revokeReason: string | null;
+}, {
+    username: string | null;
+    id: string;
+    applicationId: string;
+    revokedAt: string | null;
+    userId: string;
+    permission: string;
+    grantedByUserId: string | null;
+    grantedAt: string;
+    grantReason: string | null;
+    revokedByUserId: string | null;
+    revokeReason: string | null;
+}>;
+export declare const applicationRoleGrantListSchema: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        applicationId: z.ZodString;
+        permission: z.ZodString;
+        userId: z.ZodString;
+        /** The grantee's handle, for display. */
+        username: z.ZodNullable<z.ZodString>;
+        /** The HUMAN who granted it; null once that account was erased. */
+        grantedByUserId: z.ZodNullable<z.ZodString>;
+        grantedAt: z.ZodString;
+        grantReason: z.ZodNullable<z.ZodString>;
+        revokedAt: z.ZodNullable<z.ZodString>;
+        revokedByUserId: z.ZodNullable<z.ZodString>;
+        revokeReason: z.ZodNullable<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        username: string | null;
+        id: string;
+        applicationId: string;
+        revokedAt: string | null;
+        userId: string;
+        permission: string;
+        grantedByUserId: string | null;
+        grantedAt: string;
+        grantReason: string | null;
+        revokedByUserId: string | null;
+        revokeReason: string | null;
+    }, {
+        username: string | null;
+        id: string;
+        applicationId: string;
+        revokedAt: string | null;
+        userId: string;
+        permission: string;
+        grantedByUserId: string | null;
+        grantedAt: string;
+        grantReason: string | null;
+        revokedByUserId: string | null;
+        revokeReason: string | null;
+    }>, "many">;
+    nextCursor: z.ZodNullable<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    items: {
+        username: string | null;
+        id: string;
+        applicationId: string;
+        revokedAt: string | null;
+        userId: string;
+        permission: string;
+        grantedByUserId: string | null;
+        grantedAt: string;
+        grantReason: string | null;
+        revokedByUserId: string | null;
+        revokeReason: string | null;
+    }[];
+    nextCursor: string | null;
+}, {
+    items: {
+        username: string | null;
+        id: string;
+        applicationId: string;
+        revokedAt: string | null;
+        userId: string;
+        permission: string;
+        grantedByUserId: string | null;
+        grantedAt: string;
+        grantReason: string | null;
+        revokedByUserId: string | null;
+        revokeReason: string | null;
+    }[];
+    nextCursor: string | null;
+}>;
+/** `POST /applications/:appId/roles/grants` — name the grantee by id OR handle. */
+export declare const createApplicationRoleGrantRequestSchema: z.ZodEffects<z.ZodObject<{
+    userId: z.ZodOptional<z.ZodString>;
+    username: z.ZodOptional<z.ZodString>;
+    permission: z.ZodString;
+    reason: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+}, "strict", z.ZodTypeAny, {
+    permission: string;
+    username?: string | undefined;
+    reason?: string | undefined;
+    userId?: string | undefined;
+}, {
+    permission: string;
+    username?: string | undefined;
+    reason?: string | undefined;
+    userId?: string | undefined;
+}>, {
+    permission: string;
+    username?: string | undefined;
+    reason?: string | undefined;
+    userId?: string | undefined;
+}, {
+    permission: string;
+    username?: string | undefined;
+    reason?: string | undefined;
+    userId?: string | undefined;
+}>;
+/** `POST /applications/:appId/roles/grants/:grantId/revoke`. */
+export declare const revokeApplicationRoleGrantRequestSchema: z.ZodObject<{
+    reason: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+}, "strict", z.ZodTypeAny, {
+    reason?: string | undefined;
+}, {
+    reason?: string | undefined;
+}>;
+/** `GET /applications/:appId/roles/grants` query. */
+export declare const listApplicationRoleGrantsQuerySchema: z.ZodObject<{
+    permission: z.ZodOptional<z.ZodString>;
+    userId: z.ZodOptional<z.ZodString>;
+    includeRevoked: z.ZodOptional<z.ZodEffects<z.ZodEnum<["true", "false"]>, boolean, "true" | "false">>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    cursor: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    limit?: number | undefined;
+    cursor?: string | undefined;
+    userId?: string | undefined;
+    permission?: string | undefined;
+    includeRevoked?: boolean | undefined;
+}, {
+    limit?: number | undefined;
+    cursor?: string | undefined;
+    userId?: string | undefined;
+    permission?: string | undefined;
+    includeRevoked?: "true" | "false" | undefined;
+}>;
+/**
+ * `GET /applications/:appId/roles/me` — the keys the HUMAN behind the bearer
+ * holds for this application, in no particular order. `userId` is that human
+ * (the operator), which is NOT the account the session speaks as when a person
+ * is acting as an organization.
+ */
+export declare const applicationRolesMeSchema: z.ZodObject<{
+    applicationId: z.ZodString;
+    userId: z.ZodString;
+    permissions: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    permissions: string[];
+    applicationId: string;
+    userId: string;
+}, {
+    permissions: string[];
+    applicationId: string;
+    userId: string;
+}>;
+export type ApplicationPermissionDeclaration = z.infer<typeof applicationPermissionDeclarationSchema>;
+export type DeclareApplicationPermissionsRequest = z.infer<typeof declareApplicationPermissionsRequestSchema>;
+export type ApplicationPermissionDefinition = z.infer<typeof applicationPermissionSchema>;
+export type ApplicationPermissionList = z.infer<typeof applicationPermissionListSchema>;
+export type DeclareApplicationPermissionsResponse = z.infer<typeof declareApplicationPermissionsResponseSchema>;
+export type ApplicationRoleGrant = z.infer<typeof applicationRoleGrantSchema>;
+export type ApplicationRoleGrantList = z.infer<typeof applicationRoleGrantListSchema>;
+export type CreateApplicationRoleGrantRequest = z.infer<typeof createApplicationRoleGrantRequestSchema>;
+export type RevokeApplicationRoleGrantRequest = z.infer<typeof revokeApplicationRoleGrantRequestSchema>;
+export type ListApplicationRoleGrantsQuery = z.infer<typeof listApplicationRoleGrantsQuerySchema>;
+export type ApplicationRolesMe = z.infer<typeof applicationRolesMeSchema>;

package/dist/types/client/agentKeys.d.ts

@@ -10,8 +10,8 @@ export type AgentProofAction = (typeof AGENT_PROOF_ACTIONS)[number];
 export declare const ACCOUNT_AUTH_METHODS: readonly ["identity", "agent_key"];
 export type AccountAuthMethod = (typeof ACCOUNT_AUTH_METHODS)[number];
 export declare const agentProofClaimsCheck: import("./check").Check<{
-    expiresAt: number;
     accountId: string;
+    expiresAt: number;
     version: 1;
     audience: "oxy-api/agent";
     action: "agent_signin" | "agent_enroll" | "agent_rotate" | "agent_recover" | "agent_governance";
@@ -82,8 +82,8 @@ export declare const executeAgentKeyOperationCheck: import("./check").Check<{
 }>;
 export declare const agentKeyOperationChallengeCheck: import("./check").Check<{
     claims: {
-        expiresAt: number;
         accountId: string;
+        expiresAt: number;
         version: 1;
         audience: "oxy-api/agent";
         action: "agent_signin" | "agent_enroll" | "agent_rotate" | "agent_recover" | "agent_governance";

package/dist/types/client/check.d.ts

@@ -24,6 +24,7 @@
  *   strictObject(shape)   unknown keys FAIL (`.strict()`)
  *   looseObject(shape)    unknown keys are KEPT (`.passthrough()`)
  *   refine(c, test)       a further condition, run once `c` passes
+ *   transform(c, f)       `f` rewrites the value once `c` passes
  *   union / discriminatedUnion   as Zod 3 reports them
  *
  * A failure carries the first issue Zod would report and whether Zod would have
@@ -113,6 +114,8 @@ export declare function refineAt<T>(inner: Check<T>, test: (value: T) => {
     path: CheckPath;
     message: string;
 } | undefined): Check<T>;
+/** Zod's `.transform()`: rewrites a value `inner` accepted. */
+export declare function transform<T, U>(inner: Check<T>, rewrite: (value: T) => U): Check<U>;
 /** Narrows a checked value to a branded contract type (Zod's `.brand()`). */
 export declare function branded<T extends B, B>(inner: Check<B>): Check<T>;
 export interface ArrayRule {

package/dist/types/client/deviceSession.d.ts

@@ -72,8 +72,8 @@ export declare const sessionAccountsChangedEventCheck: import("./check").Check<{
     userId: string;
 }>;
 export declare const deviceBackgroundCredentialResponseCheck: import("./check").Check<{
-    expiresAt: string;
     accountId: string;
+    expiresAt: string;
     deviceId: string;
     secret: string;
 }>;

package/dist/types/client/index.d.ts

@@ -30,7 +30,7 @@ export { ORGANIZATION_ALIAS_KINDS, ORGANIZATION_CLAIM_DECISIONS, ORGANIZATION_CL
 export { cancelProductSubscriptionCheck, personalPlanCatalogueCheck, personalPlanCheckoutRequestCheck, personalPlanCheckoutResultCheck, productSubscriptionCancellationResultCheck, productSubscriptionsResponseCheck, subjectProductAccessCheck, subjectProductAccessQueryCheck, subscriptionCreditGrantsResponseCheck, } from './products';
 export { recommendationRequestCheck } from './recommendations';
 export { isFullReputationBalance } from './reputation';
-export { profileAccessDecisionCheck, profileAccessInputCheck } from './safety';
+export { PURCHASE_APPROVAL_STATUSES, SAFETY_POLICY_VERSION, SUPERVISED_ACTIONS, SUPERVISION_CONSENT_VERSION, SUPERVISION_INVITATION_STATUSES, SUPERVISION_STATUSES, profileAccessDecisionCheck, profileAccessInputCheck, purchaseApprovalCheck, purchaseApprovalListCheck, purchaseReviewInputCheck, safetyOrganizationsInputCheck, safetyOrganizationsResponseCheck, safetyPeopleInputCheck, safetyPeopleResponseCheck, supervisionAcceptInputCheck, supervisionContactInputCheck, supervisionContactsResponseCheck, supervisionInvitationCheck, supervisionInviteInputCheck, supervisionReviewInputCheck, supervisionStateCheck, } from './safety';
 export { publicApplicationCheck } from './sessionStatus';
 export { EMAIL_ACCOUNTS_MAX, EMAIL_SIGNIN_CHOICE_TTL_MS, EMAIL_SIGNIN_LINK_TTL_MS, EMAIL_SIGNIN_LONG_CODE_ALPHABET, EMAIL_SIGNIN_LONG_CODE_LENGTH, PASSWORD_MAX_LENGTH, PASSWORD_MIN_LENGTH, REAUTH_ACTIONS, SIGNIN_SECOND_FACTOR_MAX_ATTEMPTS, SIGNIN_SECOND_FACTOR_TTL_MS, SIGN_IN_ERROR_CODES, TOTP_BACKUP_CODE_COUNT, TOTP_DIGITS, TOTP_PERIOD_SECONDS, emailSignInChooseAccountCheck, emailSignInLinkResponseCheck, emailSignInPendingCheck, emailSignInStartResponseCheck, isEmailSignInChooseAccount, isSecondFactorRequired, normalizeEmailSignInCode, reauthProofCheck, secondFactorRequiredCheck, signInMethodsCheck, totpBackupCodesResponseCheck, totpEnrollResponseCheck, } from './signIn';
 export { BOT_USERNAME_INVALID_MESSAGE, BOT_USERNAME_SUFFIX, NUMERIC_USERNAME_MESSAGE, RESERVED_USERNAMES, RESERVED_USERNAME_MESSAGE, USERNAME_INVALID_MESSAGE, USERNAME_MAX_LENGTH, USERNAME_MIN_LENGTH, USERNAME_PATTERN_SOURCE, applyBotUsernameSuffix, botUsernameCheck, stripDisallowedUsernameCharacters, usernameCheck, usernameCheckForAccountKind, } from './username';