@wildo-ai/saas-models 1.0.1 → 1.1.0

package/dist/esm/security/api-keys/api-keys.shared.schemas.d.ts

@@ -14,50 +14,88 @@ export declare enum ApiKeyScope {
     ORGANIZATION = "organization",
     APPLICATION = "application"
 }
+/**
+ * Public API-key presentation is one cross-layer contract.
+ *
+ * A key's scope decides the prefix that identifies it to request authentication;
+ * the request itself carries the complete opaque key in the `Authorization`
+ * field without an authentication scheme. That scheme-less presentation is an
+ * application protocol contract, not OAuth bearer-token syntax. Keeping it at the shared
+ * model boundary makes minting, request routing and consumer documentation
+ * derive from one source instead of re-typing `sk_org_` / `sk_app_` in each.
+ */
+export declare const API_KEY_CREDENTIAL_PREFIX_BY_SCOPE: Readonly<Record<ApiKeyScope, string>>;
+/**
+ * API keys reuse the request-authentication field name as their transport.
+ *
+ * This aliases the protocol-wide header vocabulary rather than re-declaring a
+ * second literal. The raw value intentionally has no `Bearer` scheme, so callers
+ * must follow this application's exact wire contract rather than infer OAuth syntax.
+ * It belongs beside the prefix map because both values describe the one public
+ * presentation contract of an API-key credential.
+ */
+export declare const API_KEY_CREDENTIAL_AUTHORIZATION_HEADER: "authorization";
+/** Complete public transport/prefix presentation used by request authentication and consumer documentation. */
+export declare const API_KEY_CREDENTIAL_PRESENTATION: ApiKeyCredentialPresentation;
+export interface ApiKeyCredentialPresentation {
+    readonly authorizationHeader: string;
+    readonly prefixesByScope: Readonly<Record<ApiKeyScope, string>>;
+}
+export declare function apiKeyScopeForCredential(value: string): ApiKeyScope | null;
+export declare function isApiKeyCredential(value: string): boolean;
 export declare const ApiKeySchemaBase: z.ZodObject<{
     _id: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>;
     name: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>;
     description: z.ZodOptional<z.ZodString>;
     scope: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodEnum<typeof ApiKeyScope>>>;
-    roles: z.ZodDefault<z.ZodArray<z.ZodUnion<readonly [z.ZodEnum<typeof import("../../index.js").CORE_APP_ROLES>, z.ZodEnum<typeof import("../../index.js").CORE_ORG_ROLES>, z.ZodString]>>>;
-    status: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodEnum<typeof ApiKeyStatus>>>>;
+    roles: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodArray<z.ZodUnion<readonly [z.ZodEnum<typeof import("../..").CORE_APP_ROLES>, z.ZodEnum<typeof import("../..").CORE_ORG_ROLES>, z.ZodString]>>>>;
+    status: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodEnum<typeof ApiKeyStatus>>>>>;
     expiresAt: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodDate>>>;
     lastUsedAt: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodDate>>>>;
     createdAt: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodDate>>>>>;
     updatedAt: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodDate>>>>;
-}, z.core.$strip, core.$ZodObjectExtra>;
+    previousHashedKey: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodString>>>>>;
+    previousKeyPrefix: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodString>>>;
+    previousKeyInvalidationDate: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodDate>>>;
+}, z.core.$strip>;
 export type ApiKeyBase = z.infer<typeof ApiKeySchemaBase>;
 export declare const ApiKeyOrganizationSchema: z.ZodObject<{
     _id: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>;
     name: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>;
     description: z.ZodOptional<z.ZodString>;
-    roles: z.ZodDefault<z.ZodArray<z.ZodUnion<readonly [z.ZodEnum<typeof import("../../index.js").CORE_APP_ROLES>, z.ZodEnum<typeof import("../../index.js").CORE_ORG_ROLES>, z.ZodString]>>>;
-    status: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodEnum<typeof ApiKeyStatus>>>>;
+    roles: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodArray<z.ZodUnion<readonly [z.ZodEnum<typeof import("../..").CORE_APP_ROLES>, z.ZodEnum<typeof import("../..").CORE_ORG_ROLES>, z.ZodString]>>>>;
+    status: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodEnum<typeof ApiKeyStatus>>>>>;
     expiresAt: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodDate>>>;
     lastUsedAt: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodDate>>>>;
     createdAt: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodDate>>>>>;
     updatedAt: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodDate>>>>;
+    previousHashedKey: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodString>>>>>;
+    previousKeyPrefix: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodString>>>;
+    previousKeyInvalidationDate: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodDate>>>;
     scope: z.ZodLiteral<ApiKeyScope.ORGANIZATION>;
     organizationId: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>>>;
-    hashedKey: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>>;
+    hashedKey: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>>>>;
     keyPrefix: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>>;
-}, z.core.$strip, core.$ZodObjectExtra>;
+}, z.core.$strip>;
 export type ApiKeyOrganization = z.infer<typeof ApiKeyOrganizationSchema>;
 export declare const ApiKeyApplicationSchema: z.ZodObject<{
     _id: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>;
     name: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>;
     description: z.ZodOptional<z.ZodString>;
-    roles: z.ZodDefault<z.ZodArray<z.ZodUnion<readonly [z.ZodEnum<typeof import("../../index.js").CORE_APP_ROLES>, z.ZodEnum<typeof import("../../index.js").CORE_ORG_ROLES>, z.ZodString]>>>;
-    status: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodEnum<typeof ApiKeyStatus>>>>;
+    roles: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodArray<z.ZodUnion<readonly [z.ZodEnum<typeof import("../..").CORE_APP_ROLES>, z.ZodEnum<typeof import("../..").CORE_ORG_ROLES>, z.ZodString]>>>>;
+    status: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodEnum<typeof ApiKeyStatus>>>>>;
     expiresAt: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodDate>>>;
     lastUsedAt: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodDate>>>>;
     createdAt: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodDate>>>>>;
     updatedAt: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodDate>>>>;
+    previousHashedKey: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodString>>>>>;
+    previousKeyPrefix: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodString>>>;
+    previousKeyInvalidationDate: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodDate>>>;
     scope: z.ZodLiteral<ApiKeyScope.APPLICATION>;
     applicationId: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>>>;
-    hashedKey: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>>;
+    hashedKey: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>>>>;
     keyPrefix: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>>;
-}, z.core.$strip, core.$ZodObjectExtra>;
+}, z.core.$strip>;
 export type ApiKeyApplication = z.infer<typeof ApiKeyApplicationSchema>;
 /**
  * API Key Context for middleware and validation
@@ -66,48 +104,60 @@ export declare const ApiKeyOrganizationContextSchema: z.ZodObject<{
     _id: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>;
     name: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>;
     description: z.ZodOptional<z.ZodString>;
-    roles: z.ZodDefault<z.ZodArray<z.ZodUnion<readonly [z.ZodEnum<typeof import("../../index.js").CORE_APP_ROLES>, z.ZodEnum<typeof import("../../index.js").CORE_ORG_ROLES>, z.ZodString]>>>;
-    status: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodEnum<typeof ApiKeyStatus>>>>;
+    roles: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodArray<z.ZodUnion<readonly [z.ZodEnum<typeof import("../..").CORE_APP_ROLES>, z.ZodEnum<typeof import("../..").CORE_ORG_ROLES>, z.ZodString]>>>>;
+    status: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodEnum<typeof ApiKeyStatus>>>>>;
     expiresAt: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodDate>>>;
     lastUsedAt: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodDate>>>>;
     createdAt: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodDate>>>>>;
     updatedAt: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodDate>>>>;
+    previousHashedKey: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodString>>>>>;
+    previousKeyPrefix: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodString>>>;
+    previousKeyInvalidationDate: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodDate>>>;
     scope: z.ZodLiteral<ApiKeyScope.ORGANIZATION>;
     organizationId: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>>>;
-    hashedKey: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>>;
+    hashedKey: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>>>>;
     keyPrefix: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>>;
     rateLimit: z.ZodObject<{
-        requestsPerMinute: z.ZodNumber;
-        requestsPerHour: z.ZodNumber;
-        requestsPerDay: z.ZodNumber;
-        burstLimit: z.ZodNumber;
+        requestsPerMinute: z.ZodOptional<z.ZodNumber>;
+        requestsPerHour: z.ZodOptional<z.ZodNumber>;
+        requestsPerDay: z.ZodOptional<z.ZodNumber>;
+        customWindows: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            requestsPerWindow: z.ZodNumber;
+            windowSeconds: z.ZodNumber;
+        }, z.core.$strip>>>;
         _id: z.ZodString;
         apiKeyId: z.ZodString;
-    }, z.core.$strip, core.$ZodObjectExtra>;
-}, z.core.$strip, core.$ZodObjectExtra>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
 export type ApiKeyOrganizationContext = z.infer<typeof ApiKeyOrganizationContextSchema>;
 export declare const ApiKeyApplicationContextSchema: z.ZodObject<{
     _id: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>;
     name: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>;
     description: z.ZodOptional<z.ZodString>;
-    roles: z.ZodDefault<z.ZodArray<z.ZodUnion<readonly [z.ZodEnum<typeof import("../../index.js").CORE_APP_ROLES>, z.ZodEnum<typeof import("../../index.js").CORE_ORG_ROLES>, z.ZodString]>>>;
-    status: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodEnum<typeof ApiKeyStatus>>>>;
+    roles: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodArray<z.ZodUnion<readonly [z.ZodEnum<typeof import("../..").CORE_APP_ROLES>, z.ZodEnum<typeof import("../..").CORE_ORG_ROLES>, z.ZodString]>>>>;
+    status: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodEnum<typeof ApiKeyStatus>>>>>;
     expiresAt: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodDate>>>;
     lastUsedAt: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodDate>>>>;
     createdAt: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodDate>>>>>;
     updatedAt: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodDate>>>>;
+    previousHashedKey: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodString>>>>>;
+    previousKeyPrefix: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodString>>>;
+    previousKeyInvalidationDate: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodDate>>>;
     scope: z.ZodLiteral<ApiKeyScope.APPLICATION>;
     applicationId: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>>>;
-    hashedKey: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>>;
+    hashedKey: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>>>>;
     keyPrefix: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>>;
     rateLimit: z.ZodObject<{
-        requestsPerMinute: z.ZodNumber;
-        requestsPerHour: z.ZodNumber;
-        requestsPerDay: z.ZodNumber;
-        burstLimit: z.ZodNumber;
+        requestsPerMinute: z.ZodOptional<z.ZodNumber>;
+        requestsPerHour: z.ZodOptional<z.ZodNumber>;
+        requestsPerDay: z.ZodOptional<z.ZodNumber>;
+        customWindows: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            requestsPerWindow: z.ZodNumber;
+            windowSeconds: z.ZodNumber;
+        }, z.core.$strip>>>;
         _id: z.ZodString;
         apiKeyId: z.ZodString;
-    }, z.core.$strip, core.$ZodObjectExtra>;
-}, z.core.$strip, core.$ZodObjectExtra>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
 export type ApiKeyApplicationContext = z.infer<typeof ApiKeyApplicationContextSchema>;
 //# sourceMappingURL=api-keys.shared.schemas.d.ts.map

package/dist/esm/security/api-keys/api-keys.shared.schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api-keys.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../src/security/api-keys/api-keys.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAUxB,oBAAY,YAAY;IACtB,MAAM,WAAW;IACjB,QAAQ,aAAa;IACrB,OAAO,YAAY;CACpB;AAED,oBAAY,WAAW;IACrB,YAAY,iBAAkB;IAC9B,WAAW,gBAAkB;CAC9B;AAQD,eAAO,MAAM,gBAAgB;;;;;;;;;;;uCAW3B,CAAC;AAEH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;uCAOnC,CAAC;AAGH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAE1E,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;uCAOlC,CAAC;AAGH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAExE;;GAEG;AACH,eAAO,MAAM,+BAA+B;;;;;;;;;;;;;;;;;;;;;;uCAE1C,CAAC;AAGH,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,+BAA+B,CAAC,CAAC;AAExF,eAAO,MAAM,8BAA8B;;;;;;;;;;;;;;;;;;;;;;uCAEzC,CAAC;AAGH,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,8BAA8B,CAAC,CAAC"}
+{"version":3,"file":"api-keys.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../../src/security/api-keys/api-keys.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAWxB,oBAAY,YAAY;IACtB,MAAM,WAAW;IACjB,QAAQ,aAAa;IACrB,OAAO,YAAY;CACpB;AAED,oBAAY,WAAW;IACrB,YAAY,iBAAkB;IAC9B,WAAW,gBAAkB;CAC9B;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,kCAAkC,EAAE,QAAQ,CAAC,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,CAGnF,CAAC;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,uCAAuC,iBAAgC,CAAC;AAErF,+GAA+G;AAC/G,eAAO,MAAM,+BAA+B,EAAE,4BAG5C,CAAC;AAEH,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC,CAAC;CACjE;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAE1E;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEzD;AAQD,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;iBAyC3B,CAAC;AAEH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;iBAenC,CAAC;AAGH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAE1E,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;iBAelC,CAAC;AAGH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAExE;;GAEG;AACH,eAAO,MAAM,+BAA+B;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAE1C,CAAC;AAGH,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,+BAA+B,CAAC,CAAC;AAExF,eAAO,MAAM,8BAA8B;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAEzC,CAAC;AAGH,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,8BAA8B,CAAC,CAAC"}

package/dist/esm/security/api-keys/api-keys.shared.schemas.js

@@ -7,6 +7,7 @@
 import { z } from 'zod';
 import { RolesSchema } from '../authorizations/roles.shared.schemas.js';
 import { ApiRequest_RateLimitSchema } from '../../requests/rate-limits.shared.schemas.js';
+import { WildoHeaderKeys } from '../../requests/header-keys.shared.js';
 // ===============================
 // API KEY ENUMS
 // ===============================
@@ -21,6 +22,41 @@ export var ApiKeyScope;
     ApiKeyScope["ORGANIZATION"] = "organization";
     ApiKeyScope["APPLICATION"] = "application";
 })(ApiKeyScope || (ApiKeyScope = {}));
+/**
+ * Public API-key presentation is one cross-layer contract.
+ *
+ * A key's scope decides the prefix that identifies it to request authentication;
+ * the request itself carries the complete opaque key in the `Authorization`
+ * field without an authentication scheme. That scheme-less presentation is an
+ * application protocol contract, not OAuth bearer-token syntax. Keeping it at the shared
+ * model boundary makes minting, request routing and consumer documentation
+ * derive from one source instead of re-typing `sk_org_` / `sk_app_` in each.
+ */
+export const API_KEY_CREDENTIAL_PREFIX_BY_SCOPE = Object.freeze({
+    [ApiKeyScope.ORGANIZATION]: 'sk_org_',
+    [ApiKeyScope.APPLICATION]: 'sk_app_',
+});
+/**
+ * API keys reuse the request-authentication field name as their transport.
+ *
+ * This aliases the protocol-wide header vocabulary rather than re-declaring a
+ * second literal. The raw value intentionally has no `Bearer` scheme, so callers
+ * must follow this application's exact wire contract rather than infer OAuth syntax.
+ * It belongs beside the prefix map because both values describe the one public
+ * presentation contract of an API-key credential.
+ */
+export const API_KEY_CREDENTIAL_AUTHORIZATION_HEADER = WildoHeaderKeys.AUTHORIZATION;
+/** Complete public transport/prefix presentation used by request authentication and consumer documentation. */
+export const API_KEY_CREDENTIAL_PRESENTATION = Object.freeze({
+    authorizationHeader: API_KEY_CREDENTIAL_AUTHORIZATION_HEADER,
+    prefixesByScope: API_KEY_CREDENTIAL_PREFIX_BY_SCOPE,
+});
+export function apiKeyScopeForCredential(value) {
+    return Object.values(ApiKeyScope).find((scope) => value.startsWith(API_KEY_CREDENTIAL_PREFIX_BY_SCOPE[scope])) ?? null;
+}
+export function isApiKeyCredential(value) {
+    return apiKeyScopeForCredential(value) !== null;
+}
 // ===============================
 // CORE API KEY SCHEMAS
 // ===============================
@@ -30,19 +66,56 @@ export const ApiKeySchemaBase = z.object({
     name: z.string().min(1).max(100).isDBIndexed().isSummaryField(),
     description: z.string().max(500).optional(),
     scope: z.enum(ApiKeyScope).isDBIndexed().isSummaryField(),
-    roles: z.array(RolesSchema).default([]),
-    status: z.enum(ApiKeyStatus).default(ApiKeyStatus.ACTIVE).isDBIndexed().isSummaryField(),
+    // `.isAuditEvidence()` on both: a machine credential's roles ARE its authority, and its status
+    // decides whether that authority is live. This resource exposes no core UPDATE and gates roles
+    // only at minting, so the before/after values are the only way to reconstruct what a key could
+    // do at a point in time. Closed vocabulary — no personal data reaches the audit ledger.
+    // assurance-control: WILDO.ACCESS.PRIVILEGE_EVIDENCE
+    roles: z.array(RolesSchema).default([]).isAuditEvidence(),
+    status: z.enum(ApiKeyStatus).default(ApiKeyStatus.ACTIVE).isDBIndexed().isSummaryField().isAuditEvidence(),
     expiresAt: z.date().optional().isDBIndexed().isSummaryField(),
     lastUsedAt: z.date().optional().isDBIndexed().excludeFromCreate().excludeFromUpdate(),
     createdAt: z.date().default(() => new Date()).isDBIndexed().isSummaryField().excludeFromCreate().excludeFromUpdate(),
-    updatedAt: z.date().default(() => new Date()).isDBIndexed().excludeFromCreate().excludeFromUpdate()
+    updatedAt: z.date().default(() => new Date()).isDBIndexed().excludeFromCreate().excludeFromUpdate(),
+    // ── Rotation grace window ─────────────────────────────────────────────────
+    // When a key is ROTATED or REGENERATEd, the PRIOR secret is retained here so it
+    // keeps authenticating during an overlap window — callers can migrate to the new
+    // secret without a hard cutover. The bearer-token auth path
+    // (`execution-context-creator.backend.service.ts`) resolves a presented key against
+    // the current `hashedKey` OR this `previousHashedKey` while the window is open
+    // (`previousKeyInvalidationDate` is null or in the future) AND the key is ACTIVE.
+    // All three are server-managed by the rotate/regenerate impls only — never
+    // client-settable (`.excludeFromCreate().excludeFromUpdate()`).
+    //
+    // `previousHashedKey` — `sha256` of the prior secret; the auth path looks a
+    // presented key up against it, so it is `.isDBIndexed()`. Backend-only (a secret
+    // hash, never surfaced). Absent until the first rotation.
+    previousHashedKey: z.string().min(1).optional().isDBIndexed().isBackendOnly().excludeFromCreate().excludeFromUpdate(),
+    // First 8 chars of the prior secret — retained for support/audit display while the
+    // previous secret is still valid (not a secret, so surfaced). Overwritten on the
+    // next rotation.
+    previousKeyPrefix: z.string().length(8).optional().excludeFromCreate().excludeFromUpdate(),
+    // When the previous secret stops authenticating. `null`/absent = no scheduled
+    // invalidation (REGENERATE overlap — the prior secret stays valid until the next
+    // rotation). A future date (ROTATE `oldKeyInvalidationDate`) = honored until then,
+    // then rejected. `now`/past (ROTATE default) = immediate hard cutover. Surfaced so
+    // operators can see when the old secret dies.
+    previousKeyInvalidationDate: z.date().optional().excludeFromCreate().excludeFromUpdate()
 });
 export const ApiKeyOrganizationSchema = ApiKeySchemaBase.extend({
     scope: z.literal(ApiKeyScope.ORGANIZATION),
     organizationId: z.string().min(1).isDBIndexed().isForeignKey().isSummaryField().excludeFromUpdate(),
     // Backend-only field - stored in DB but never sent to frontend (security)
     // excludeFromCreate ensures it doesn't appear in forms; isBackendOnly ensures it's stripped from responses
-    hashedKey: z.string().min(1).isBackendOnly({ isReturnedAtCreation: true }).excludeFromCreate().excludeFromUpdate(),
+    // M3 (third-pass review): `hashedKey` is the lookup key for bearer-token
+    // auth (`registry-bearer-token.middleware.ts` resolves api-keys by it
+    // on every authenticated request). Without an index this is an O(n)
+    // collection scan per request. Compound unique guarantees only one
+    // active row per hash — cryptographically near-impossible by accident,
+    // but a uniqueness contract avoids two rows being returned to the
+    // resolver on a hash-collision and prevents shadow-key duplicates
+    // during rotation.
+    hashedKey: z.string().min(1).isDBIndexed().isUnique().isBackendOnly({ isReturnedAtCreation: true }).excludeFromCreate().excludeFromUpdate(),
     keyPrefix: z.string().length(8).isSummaryField().excludeFromCreate().excludeFromUpdate(),
 });
 export const ApiKeyApplicationSchema = ApiKeySchemaBase.extend({
@@ -50,7 +123,15 @@ export const ApiKeyApplicationSchema = ApiKeySchemaBase.extend({
     applicationId: z.string().min(1).isDBIndexed().isForeignKey().isSummaryField().excludeFromUpdate(),
     // Backend-only field - stored in DB but never sent to frontend (security)
     // excludeFromCreate ensures it doesn't appear in forms; isBackendOnly ensures it's stripped from responses
-    hashedKey: z.string().min(1).isBackendOnly({ isReturnedAtCreation: true }).excludeFromCreate().excludeFromUpdate(),
+    // M3 (third-pass review): `hashedKey` is the lookup key for bearer-token
+    // auth (`registry-bearer-token.middleware.ts` resolves api-keys by it
+    // on every authenticated request). Without an index this is an O(n)
+    // collection scan per request. Compound unique guarantees only one
+    // active row per hash — cryptographically near-impossible by accident,
+    // but a uniqueness contract avoids two rows being returned to the
+    // resolver on a hash-collision and prevents shadow-key duplicates
+    // during rotation.
+    hashedKey: z.string().min(1).isDBIndexed().isUnique().isBackendOnly({ isReturnedAtCreation: true }).excludeFromCreate().excludeFromUpdate(),
     keyPrefix: z.string().length(8).isSummaryField().excludeFromCreate().excludeFromUpdate(),
 });
 /**
@@ -62,4 +143,4 @@ export const ApiKeyOrganizationContextSchema = ApiKeyOrganizationSchema.extend({
 export const ApiKeyApplicationContextSchema = ApiKeyApplicationSchema.extend({
     rateLimit: ApiRequest_RateLimitSchema
 });
-//# sourceMappingURL=api-keys.shared.schemas.js.map
+//# sourceMappingURL=api-keys.shared.schemas.js.map

package/dist/esm/security/api-keys/api-keys.shared.schemas.js.map

@@ -1 +1 @@
-{"version":3,"file":"api-keys.shared.schemas.js","sourceRoot":"","sources":["../../../../src/security/api-keys/api-keys.shared.schemas.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"api-keys.shared.schemas.js","sourceRoot":"","sources":["../../../../../src/security/api-keys/api-keys.shared.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * API Key Shared Schemas\n *\n * Frontend/backend shared API key schemas and DTOs only.\n * Backend-specific logic stays in saas-backend-lib.\n */\n\nimport { z } from 'zod';\nimport { RolesSchema } from '../authorizations/roles.shared.schemas';\nimport { ApiRequest_RateLimitSchema} from '../../requests/rate-limits.shared.schemas';\nimport { WildoHeaderKeys } from '../../requests/header-keys.shared';\n\n// ===============================\n// API KEY ENUMS\n// ===============================\n\n\n\nexport enum ApiKeyStatus {\n  ACTIVE = 'active',\n  INACTIVE = 'inactive',\n  EXPIRED = 'expired'\n}\n\nexport enum ApiKeyScope {\n  ORGANIZATION  = 'organization',\n  APPLICATION   = 'application',\n}\n\n/**\n * Public API-key presentation is one cross-layer contract.\n *\n * A key's scope decides the prefix that identifies it to request authentication;\n * the request itself carries the complete opaque key in the `Authorization`\n * field without an authentication scheme. That scheme-less presentation is an\n * application protocol contract, not OAuth bearer-token syntax. Keeping it at the shared\n * model boundary makes minting, request routing and consumer documentation\n * derive from one source instead of re-typing `sk_org_` / `sk_app_` in each.\n */\nexport const API_KEY_CREDENTIAL_PREFIX_BY_SCOPE: Readonly<Record<ApiKeyScope, string>> = Object.freeze({\n  [ApiKeyScope.ORGANIZATION]: 'sk_org_',\n  [ApiKeyScope.APPLICATION]: 'sk_app_',\n});\n\n/**\n * API keys reuse the request-authentication field name as their transport.\n *\n * This aliases the protocol-wide header vocabulary rather than re-declaring a\n * second literal. The raw value intentionally has no `Bearer` scheme, so callers\n * must follow this application's exact wire contract rather than infer OAuth syntax.\n * It belongs beside the prefix map because both values describe the one public\n * presentation contract of an API-key credential.\n */\nexport const API_KEY_CREDENTIAL_AUTHORIZATION_HEADER = WildoHeaderKeys.AUTHORIZATION;\n\n/** Complete public transport/prefix presentation used by request authentication and consumer documentation. */\nexport const API_KEY_CREDENTIAL_PRESENTATION: ApiKeyCredentialPresentation = Object.freeze({\n  authorizationHeader: API_KEY_CREDENTIAL_AUTHORIZATION_HEADER,\n  prefixesByScope: API_KEY_CREDENTIAL_PREFIX_BY_SCOPE,\n});\n\nexport interface ApiKeyCredentialPresentation {\n  readonly authorizationHeader: string;\n  readonly prefixesByScope: Readonly<Record<ApiKeyScope, string>>;\n}\n\nexport function apiKeyScopeForCredential(value: string): ApiKeyScope | null {\n  return (Object.values(ApiKeyScope) as ApiKeyScope[]).find((scope) => value.startsWith(API_KEY_CREDENTIAL_PREFIX_BY_SCOPE[scope])) ?? null;\n}\n\nexport function isApiKeyCredential(value: string): boolean {\n  return apiKeyScopeForCredential(value) !== null;\n}\n\n\n// ===============================\n// CORE API KEY SCHEMAS\n// ===============================\n\n// Base schema for extension (needs to be z.object for extend to work)\nexport const ApiKeySchemaBase = z.object({\n  _id: z.string().min(1).isPrimaryKey().isSummaryField(),\n  name: z.string().min(1).max(100).isDBIndexed().isSummaryField(),\n  description: z.string().max(500).optional(),\n  scope: z.enum(ApiKeyScope).isDBIndexed().isSummaryField(),\n  // `.isAuditEvidence()` on both: a machine credential's roles ARE its authority, and its status\n  // decides whether that authority is live. This resource exposes no core UPDATE and gates roles\n  // only at minting, so the before/after values are the only way to reconstruct what a key could\n  // do at a point in time. Closed vocabulary — no personal data reaches the audit ledger.\n  // assurance-control: WILDO.ACCESS.PRIVILEGE_EVIDENCE\n  roles: z.array(RolesSchema).default([]).isAuditEvidence(),\n  status: z.enum(ApiKeyStatus).default(ApiKeyStatus.ACTIVE).isDBIndexed().isSummaryField().isAuditEvidence(),\n  expiresAt: z.date().optional().isDBIndexed().isSummaryField(),\n  lastUsedAt: z.date().optional().isDBIndexed().excludeFromCreate().excludeFromUpdate(),\n  createdAt: z.date().default(() => new Date()).isDBIndexed().isSummaryField().excludeFromCreate().excludeFromUpdate(),\n  updatedAt: z.date().default(() => new Date()).isDBIndexed().excludeFromCreate().excludeFromUpdate(),\n\n  // ── Rotation grace window ─────────────────────────────────────────────────\n  // When a key is ROTATED or REGENERATEd, the PRIOR secret is retained here so it\n  // keeps authenticating during an overlap window — callers can migrate to the new\n  // secret without a hard cutover. The bearer-token auth path\n  // (`execution-context-creator.backend.service.ts`) resolves a presented key against\n  // the current `hashedKey` OR this `previousHashedKey` while the window is open\n  // (`previousKeyInvalidationDate` is null or in the future) AND the key is ACTIVE.\n  // All three are server-managed by the rotate/regenerate impls only — never\n  // client-settable (`.excludeFromCreate().excludeFromUpdate()`).\n  //\n  // `previousHashedKey` — `sha256` of the prior secret; the auth path looks a\n  // presented key up against it, so it is `.isDBIndexed()`. Backend-only (a secret\n  // hash, never surfaced). Absent until the first rotation.\n  previousHashedKey: z.string().min(1).optional().isDBIndexed().isBackendOnly().excludeFromCreate().excludeFromUpdate(),\n  // First 8 chars of the prior secret — retained for support/audit display while the\n  // previous secret is still valid (not a secret, so surfaced). Overwritten on the\n  // next rotation.\n  previousKeyPrefix: z.string().length(8).optional().excludeFromCreate().excludeFromUpdate(),\n  // When the previous secret stops authenticating. `null`/absent = no scheduled\n  // invalidation (REGENERATE overlap — the prior secret stays valid until the next\n  // rotation). A future date (ROTATE `oldKeyInvalidationDate`) = honored until then,\n  // then rejected. `now`/past (ROTATE default) = immediate hard cutover. Surfaced so\n  // operators can see when the old secret dies.\n  previousKeyInvalidationDate: z.date().optional().excludeFromCreate().excludeFromUpdate()\n});\n\nexport type ApiKeyBase = z.infer<typeof ApiKeySchemaBase>;\n\nexport const ApiKeyOrganizationSchema = ApiKeySchemaBase.extend({\n  scope: z.literal(ApiKeyScope.ORGANIZATION),\n  organizationId: z.string().min(1).isDBIndexed().isForeignKey().isSummaryField().excludeFromUpdate(),\n  // Backend-only field - stored in DB but never sent to frontend (security)\n  // excludeFromCreate ensures it doesn't appear in forms; isBackendOnly ensures it's stripped from responses\n  // M3 (third-pass review): `hashedKey` is the lookup key for bearer-token\n  // auth (`registry-bearer-token.middleware.ts` resolves api-keys by it\n  // on every authenticated request). Without an index this is an O(n)\n  // collection scan per request. Compound unique guarantees only one\n  // active row per hash — cryptographically near-impossible by accident,\n  // but a uniqueness contract avoids two rows being returned to the\n  // resolver on a hash-collision and prevents shadow-key duplicates\n  // during rotation.\n  hashedKey: z.string().min(1).isDBIndexed().isUnique().isBackendOnly({ isReturnedAtCreation : true }).excludeFromCreate().excludeFromUpdate(),\n  keyPrefix: z.string().length(8).isSummaryField().excludeFromCreate().excludeFromUpdate(),\n});\n\n\nexport type ApiKeyOrganization = z.infer<typeof ApiKeyOrganizationSchema>;\n\nexport const ApiKeyApplicationSchema = ApiKeySchemaBase.extend({\n  scope: z.literal(ApiKeyScope.APPLICATION),\n  applicationId: z.string().min(1).isDBIndexed().isForeignKey().isSummaryField().excludeFromUpdate(),\n  // Backend-only field - stored in DB but never sent to frontend (security)\n  // excludeFromCreate ensures it doesn't appear in forms; isBackendOnly ensures it's stripped from responses\n  // M3 (third-pass review): `hashedKey` is the lookup key for bearer-token\n  // auth (`registry-bearer-token.middleware.ts` resolves api-keys by it\n  // on every authenticated request). Without an index this is an O(n)\n  // collection scan per request. Compound unique guarantees only one\n  // active row per hash — cryptographically near-impossible by accident,\n  // but a uniqueness contract avoids two rows being returned to the\n  // resolver on a hash-collision and prevents shadow-key duplicates\n  // during rotation.\n  hashedKey: z.string().min(1).isDBIndexed().isUnique().isBackendOnly({ isReturnedAtCreation : true }).excludeFromCreate().excludeFromUpdate(),\n  keyPrefix: z.string().length(8).isSummaryField().excludeFromCreate().excludeFromUpdate(),\n});\n\n\nexport type ApiKeyApplication = z.infer<typeof ApiKeyApplicationSchema>;\n\n/**\n * API Key Context for middleware and validation\n */\nexport const ApiKeyOrganizationContextSchema = ApiKeyOrganizationSchema.extend({\n  rateLimit: ApiRequest_RateLimitSchema\n});\n\n\nexport type ApiKeyOrganizationContext = z.infer<typeof ApiKeyOrganizationContextSchema>;\n\nexport const ApiKeyApplicationContextSchema = ApiKeyApplicationSchema.extend({\n  rateLimit: ApiRequest_RateLimitSchema\n});\n\n\nexport type ApiKeyApplicationContext = z.infer<typeof ApiKeyApplicationContextSchema>;\n"]}

package/dist/esm/security/authentications/anonymous-session/anonymous-session.shared.contract.d.ts

@@ -0,0 +1,185 @@
+/**
+ * Anonymous Session — Shared Contract (W7.3a)
+ *
+ * Single source of truth for the constants/keys/format/state-machine
+ * shape that any consumer of the anonymous-session feature MUST agree
+ * on, regardless of runtime (browser, Astro static page, Node service).
+ *
+ * Consumers today:
+ * - `engine/saas-frontend-lib`'s `AnonymousSessionContext.tsx` and
+ *   `local-storage.frontend.schemas.ts` (SaaS app, React, full HTTP
+ *   client integration)
+ * - `engine/saas-backend-lib`'s
+ *   `security/authentications/services/anonymous-session.backend.service.ts`
+ *   (JWT signing/verification, transposition, cleanup)
+ * - `engine/saas-website` (planned) — light, independent
+ *   `WebsiteAnonymousSessionContext` for the marketing/landing site
+ *   that intentionally does NOT depend on `saas-frontend-lib` to keep
+ *   the static-built bundle small (per `saas-website-slice.md` D16
+ *   Q17=B)
+ *
+ * Why the contract lives here (in `saas-models`) and not in
+ * `saas-frontend-lib`:
+ *
+ * The marketing-website implementation must NOT import
+ * `saas-frontend-lib` (it would pull in the full SaaS-app shell, MUI,
+ * react-router, etc. — orders of magnitude larger than a marketing
+ * site needs). At the same time, the marketing site MUST be
+ * bit-compatible with the SaaS-app implementation so a user who
+ * starts a session on `example.com` and continues on
+ * `app.example.com` keeps the same `anonymousUserId`. The only safe
+ * way to enforce that is to extract the concrete keys/headers/JWT
+ * format/state-machine vocabulary into a React-free, runtime-free
+ * module that all three consumers import from. Drift is then a
+ * compile/test failure, not a silent runtime divergence.
+ *
+ * A cross-package conformance test
+ * (`__tests__/anonymous-session.contract.conformance.test.ts`)
+ * asserts that `saas-frontend-lib`'s public surface and
+ * `saas-backend-lib`'s service implementation reference the canonical
+ * values from this file.
+ */
+import { z } from 'zod';
+/**
+ * The exact `localStorage.getItem`/`setItem` keys used to persist the
+ * anonymous session across page reloads and tabs.
+ *
+ * MUST stay in sync with
+ * `engine/saas-frontend-lib/src/core/commons/local-storage.frontend.schemas.ts`
+ * (`LOCAL_STORAGE_KEYS.ANONYMOUS_USER_ID` /
+ * `LOCAL_STORAGE_KEYS.ANONYMOUS_SESSION_TOKEN`) — that enum re-exports
+ * from this contract, so a single edit here propagates everywhere.
+ *
+ * Cross-tab sync via the `storage` event keys off these strings
+ * literally — changing them is a breaking change for any user with an
+ * existing localStorage entry.
+ */
+export declare const ANONYMOUS_SESSION_LOCAL_STORAGE_KEYS: {
+    readonly ANONYMOUS_USER_ID: "anonymousUserId";
+    readonly ANONYMOUS_SESSION_TOKEN: "anonymousSessionToken";
+};
+export type AnonymousSessionLocalStorageKey = typeof ANONYMOUS_SESSION_LOCAL_STORAGE_KEYS[keyof typeof ANONYMOUS_SESSION_LOCAL_STORAGE_KEYS];
+/**
+ * The canonical HTTP header names used by the anonymous-session
+ * protocol.
+ *
+ * These values are NOT redefined here — they are re-exported aliases
+ * from `WildoHeaderKeys` (the single source of truth for all
+ * platform header names, in `requests/header-keys.shared.ts`). The
+ * alias exists purely so anonymous-session consumers have a single
+ * import for everything they need.
+ *
+ * - `INIT`: client → server, on the FIRST request that creates the
+ *   AnonymousUser record. Carries the freshly-generated UUID. Server
+ *   responds with `TOKEN` (the signed JWT).
+ * - `SESSION`: client → server, on every SUBSEQUENT request once the
+ *   JWT is held. Carries the JWT in the body of the header value.
+ * - `TOKEN`: server → client, in the response that completes
+ *   initialization. Carries the freshly-signed JWT.
+ */
+export declare const ANONYMOUS_SESSION_HTTP_HEADERS: {
+    readonly INIT: "x-anonymous-session-init";
+    readonly SESSION: "x-anonymous-session";
+    readonly TOKEN: "x-anonymous-session-token";
+};
+export type AnonymousSessionHttpHeader = typeof ANONYMOUS_SESSION_HTTP_HEADERS[keyof typeof ANONYMOUS_SESSION_HTTP_HEADERS];
+/**
+ * The cryptographic format for the anonymous-session JWT.
+ *
+ * Concrete values (algorithm, expiry) are pinned here so the backend
+ * and any client that wants to parse the JWT (for diagnostic
+ * purposes, e.g. expiry-aware UI) agree on the bit-level shape.
+ *
+ * - `algorithm`: HMAC-SHA256 — symmetric, signed with
+ *   `configService.secrets.security.session.secret`. Symmetric is
+ *   acceptable because verification only happens server-side
+ *   (clients treat the JWT as opaque); switching to RS256 would
+ *   require shipping a public key to the marketing site for nothing.
+ * - `expirySeconds`: 24 hours — long enough to cover a typical
+ *   marketing → app conversion funnel that may span multiple
+ *   sessions, short enough to bound exposure if a token leaks. The
+ *   `cleanupExpiredSessions` batch uses a 48h `sessionTtlMs` to
+ *   leave a comfortable buffer between JWT expiry and DB cleanup.
+ *
+ * The string `'24h'` is the legacy expiry encoding (jsonwebtoken
+ * accepts both `'24h'` and `expirySeconds`). The contract exposes
+ * `expirySeconds` as the canonical numeric form; consumers using the
+ * `jsonwebtoken` library can convert via
+ * `${ANONYMOUS_SESSION_JWT_FORMAT.expirySeconds}s`.
+ */
+export declare const ANONYMOUS_SESSION_JWT_FORMAT: {
+    readonly algorithm: "HS256";
+    readonly expirySeconds: 86400;
+};
+/**
+ * Convenience: jsonwebtoken's expiresIn-friendly string form.
+ * Equivalent to `${expirySeconds}s` but pre-computed.
+ */
+export declare const ANONYMOUS_SESSION_JWT_EXPIRY_STRING: "24h";
+/**
+ * The exact shape of the JWT payload signed/verified for an
+ * anonymous session.
+ *
+ * Both the backend (`signSessionToken` / `verifySessionToken`) and
+ * any future client-side parser (e.g. for diagnostic UI showing
+ * "session expires in N hours") must produce/consume payloads
+ * matching this schema.
+ *
+ * - `anonymousUserId`: the client-generated session UUID — the
+ *   AnonymousUser's `uuidRef` (its relational identity), NOT the
+ *   server-minted MongoDB `_id`. The backend resolves ownership by
+ *   matching this against child `anonymousUserId` FKs (which carry the
+ *   same `uuidRef`) and the parent row's `uuidRef` during transposition.
+ *   Kept named `anonymousUserId` for wire/localStorage stability.
+ * - `iat`/`exp`: standard JWT claims (seconds since epoch). Set by
+ *   `jsonwebtoken.sign()` automatically based on
+ *   `ANONYMOUS_SESSION_JWT_FORMAT.expirySeconds`.
+ */
+export declare const AnonymousSessionJwtPayloadSchema: z.ZodObject<{
+    anonymousUserId: z.ZodString;
+    iat: z.ZodNumber;
+    exp: z.ZodNumber;
+}>;
+export type AnonymousSessionJwtPayload = z.infer<typeof AnonymousSessionJwtPayloadSchema>;
+/**
+ * The five client-side states an anonymous session passes through.
+ *
+ * This enum is the SHARED vocabulary between
+ * `saas-frontend-lib`'s React `AnonymousSessionContext` and
+ * `saas-website`'s lighter `WebsiteAnonymousSessionContext` — both
+ * implement reducers over the same five states so debugging tooling
+ * and conformance tests can reason about either one identically.
+ *
+ * State transitions (enforced by each implementation's reducer):
+ *
+ *   IDLE → INITIALIZING : `initAnonymousSession()` is called; UUID
+ *                          generated; first API call in flight with
+ *                          `x-anonymous-session-init` header.
+ *   INITIALIZING → ACTIVE : server responds with
+ *                          `x-anonymous-session-token`; JWT stored.
+ *   ACTIVE → ACTIVE      : token rotation (new JWT received on a
+ *                          subsequent response).
+ *   ACTIVE → TRANSPOSING : user starts to log in / register —
+ *                          subsequent anonymous-session API calls are
+ *                          blocked until backend transposition
+ *                          finishes.
+ *   TRANSPOSING → CLEARED : backend transposition complete; auth
+ *                          session takes over; localStorage entries
+ *                          removed.
+ *   * → CLEARED          : explicit logout/clear (rare on marketing
+ *                          site; common on app side).
+ *
+ * Each implementation's reducer is responsible for rejecting illegal
+ * transitions silently (return current state) — the conformance test
+ * verifies both reducers agree on the legal-transition matrix.
+ */
+export declare enum AnonymousSessionStateMachineStatesEnum {
+    IDLE = "IDLE",
+    INITIALIZING = "INITIALIZING",
+    ACTIVE = "ACTIVE",
+    TRANSPOSING = "TRANSPOSING",
+    CLEARED = "CLEARED"
+}
+export declare const AnonymousSessionStateMachineStatesSchema: z.ZodEnum<typeof AnonymousSessionStateMachineStatesEnum>;
+export type AnonymousSessionStateMachineState = z.infer<typeof AnonymousSessionStateMachineStatesSchema>;
+//# sourceMappingURL=anonymous-session.shared.contract.d.ts.map

package/dist/esm/security/authentications/anonymous-session/anonymous-session.shared.contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"anonymous-session.shared.contract.d.ts","sourceRoot":"","sources":["../../../../../../src/security/authentications/anonymous-session/anonymous-session.shared.contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAQxB;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,oCAAoC;;;CAGvC,CAAC;AAEX,MAAM,MAAM,+BAA+B,GACzC,OAAO,oCAAoC,CAAC,MAAM,OAAO,oCAAoC,CAAC,CAAC;AAOjG;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,8BAA8B;;;;CAIjC,CAAC;AAEX,MAAM,MAAM,0BAA0B,GACpC,OAAO,8BAA8B,CAAC,MAAM,OAAO,8BAA8B,CAAC,CAAC;AAOrF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,4BAA4B;;;CAG/B,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,mCAAmC,EAAG,KAAc,CAAC;AAOlE;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,gCAAgC,EAAE,CAAC,CAAC,SAAS,CAAC;IACzD,eAAe,EAAE,CAAC,CAAC,SAAS,CAAC;IAC7B,GAAG,EAAc,CAAC,CAAC,SAAS,CAAC;IAC7B,GAAG,EAAc,CAAC,CAAC,SAAS,CAAC;CAC9B,CAIC,CAAC;AAEH,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gCAAgC,CAAC,CAAC;AAO1F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,oBAAY,sCAAsC;IAChD,IAAI,SAAiB;IACrB,YAAY,iBAAiB;IAC7B,MAAM,WAAiB;IACvB,WAAW,gBAAiB;IAC5B,OAAO,YAAiB;CACzB;AAED,eAAO,MAAM,wCAAwC,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,sCAAsC,CAC9D,CAAC;AAEjD,MAAM,MAAM,iCAAiC,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wCAAwC,CAAC,CAAC"}