@salamandradevs/core 0.1.4 → 0.2.0

package/types/keys/schema.d.ts

@@ -0,0 +1,73 @@
+import { z } from 'zod';
+/**
+ * Public JSON Web Key material schema.
+ *
+ * - Kty: Key type.
+ * - Kid: Public key identifier.
+ * - Use: Optional intended key use.
+ * - Alg: Optional JOSE algorithm.
+ * - Crv: Optional elliptic curve name.
+ * - X: Optional elliptic-curve or RSA coordinate.
+ * - Y: Optional elliptic-curve coordinate.
+ * - N: Optional RSA modulus.
+ * - E: Optional RSA exponent.
+ *
+ * @remarks
+ * Provider-neutral: this is the public key as served to every key consumer, so it carries
+ * no provider-specific fields. Shared across every signing-key provider so each validates
+ * the lifecycle document against one definition.
+ * @group Keys
+ * @category Key Providers
+ */
+export declare const publicJwkSchema: z.ZodObject<{
+    kty: z.ZodString;
+    kid: z.ZodString;
+    use: z.ZodOptional<z.ZodString>;
+    alg: z.ZodOptional<z.ZodString>;
+    crv: z.ZodOptional<z.ZodString>;
+    x: z.ZodOptional<z.ZodString>;
+    y: z.ZodOptional<z.ZodString>;
+    n: z.ZodOptional<z.ZodString>;
+    e: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/**
+ * Durable signing-key lifecycle document schema.
+ *
+ * - CurrentKid: Identifier of the sole active key.
+ * - Keys: Complete provider-managed key lifecycle.
+ *
+ * @remarks
+ * The neutral contract every provider's durable store must satisfy. Behavioural invariants
+ * beyond this shape (exactly one active key, status-consistent timestamps) live in
+ * {@link validateSigningKeyState}.
+ * @group Keys
+ * @category Key Providers
+ */
+export declare const signingKeyStateSchema: z.ZodObject<{
+    currentKid: z.ZodNullable<z.ZodString>;
+    keys: z.ZodArray<z.ZodObject<{
+        kid: z.ZodString;
+        providerKeyId: z.ZodString;
+        status: z.ZodEnum<{
+            pending: "pending";
+            active: "active";
+            retired: "retired";
+        }>;
+        publicJwk: z.ZodObject<{
+            kty: z.ZodString;
+            kid: z.ZodString;
+            use: z.ZodOptional<z.ZodString>;
+            alg: z.ZodOptional<z.ZodString>;
+            crv: z.ZodOptional<z.ZodString>;
+            x: z.ZodOptional<z.ZodString>;
+            y: z.ZodOptional<z.ZodString>;
+            n: z.ZodOptional<z.ZodString>;
+            e: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+        activateAfter: z.ZodPipe<z.ZodString, z.ZodISODateTime>;
+        activatedAt: z.ZodNullable<z.ZodPipe<z.ZodString, z.ZodISODateTime>>;
+        retiredAt: z.ZodNullable<z.ZodPipe<z.ZodString, z.ZodISODateTime>>;
+        verifyUntil: z.ZodNullable<z.ZodPipe<z.ZodString, z.ZodISODateTime>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+//# sourceMappingURL=schema.d.ts.map

package/types/keys/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/keys/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;kBAYjB,CAAC;AAEZ;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;kBAkBvB,CAAC"}

package/types/keys/types.d.ts

@@ -0,0 +1,53 @@
+/** Public JSON Web Key material. */
+export type PublicJwk = Readonly<{
+    kty: string;
+    kid: string;
+    use?: string;
+    alg?: string;
+    crv?: string;
+    x?: string;
+    y?: string;
+    n?: string;
+    e?: string;
+}>;
+/** Signing capability bound to one provider-managed key. */
+export type SigningKeyHandle = Readonly<{
+    kid: string;
+    algorithm: 'ES256';
+    sign: (input: Uint8Array) => Promise<Uint8Array>;
+}>;
+/** Lifecycle state of a provider-managed signing key. */
+export type SigningKeyStatus = 'pending' | 'active' | 'retired';
+/**
+ * Durable metadata for one provider-managed signing key.
+ *
+ * - Kid: Public identifier carried with each signature.
+ * - ProviderKeyId: Opaque provider-owned key identifier.
+ * - Status: Current lifecycle status.
+ * - PublicJwk: Public verification key published through JWKS.
+ * - ActivateAfter: Earliest time when a pending key may become active.
+ * - ActivatedAt: Activation time, or null while pending.
+ * - RetiredAt: Retirement time, or null while active or pending.
+ * - VerifyUntil: Verification end time, or null while not retired.
+ */
+export type SigningKeyEntry = Readonly<{
+    kid: string;
+    providerKeyId: string;
+    status: SigningKeyStatus;
+    publicJwk: PublicJwk;
+    activateAfter: string;
+    activatedAt: string | null;
+    retiredAt: string | null;
+    verifyUntil: string | null;
+}>;
+/**
+ * Durable lifecycle state shared by the replicas that own one key set.
+ *
+ * - CurrentKid: Identifier of the sole active key.
+ * - Keys: Complete provider-managed key lifecycle.
+ */
+export type SigningKeyState = Readonly<{
+    currentKid: string | null;
+    keys: readonly SigningKeyEntry[];
+}>;
+//# sourceMappingURL=types.d.ts.map

package/types/keys/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/keys/types.ts"],"names":[],"mappings":"AAAA,oCAAoC;AACpC,MAAM,MAAM,SAAS,GAAG,QAAQ,CAAC;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,CAAC,CAAC,EAAE,MAAM,CAAC;CACZ,CAAC,CAAC;AAEH,4DAA4D;AAC5D,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC;IACtC,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,OAAO,CAAC;IACnB,IAAI,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;CAClD,CAAC,CAAC;AAEH,yDAAyD;AACzD,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEhE;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,eAAe,GAAG,QAAQ,CAAC;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,gBAAgB,CAAC;IACzB,SAAS,EAAE,SAAS,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B,CAAC,CAAC;AAEH;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,QAAQ,CAAC;IACrC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,IAAI,EAAE,SAAS,eAAe,EAAE,CAAC;CAClC,CAAC,CAAC"}

package/types/keys/validation.d.ts

@@ -0,0 +1,19 @@
+import type { SigningKeyState } from './types.js';
+/**
+ * Parses the signing-key lifecycle document and enforces every invariant providers rely on.
+ *
+ * @remarks
+ * Shared by every signing-key provider so the lifecycle invariants have one definition:
+ * unique identifiers, an ES256 P-256 public JWK per entry whose `kid` matches its entry,
+ * status-consistent timestamps, exactly one active key, at most one pending key, and a
+ * `currentKid` that names the active key. Nothing downstream re-checks any of this, so a
+ * failure here is fatal on purpose.
+ * @group Keys
+ * @category Key Providers
+ * @param value - Raw lifecycle document read from a provider's durable store.
+ * @param algorithm - JOSE algorithm every published key must declare.
+ * @returns Validated signing-key state.
+ * @throws {CustomError} KEYS_PROVIDER_ERROR when any signing-key invariant fails.
+ */
+export declare function validateSigningKeyState(value: unknown, algorithm: 'ES256'): SigningKeyState;
+//# sourceMappingURL=validation.d.ts.map

package/types/keys/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/keys/validation.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAmB,eAAe,EAAE,MAAM,YAAY,CAAC;AAEnE;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,OAAO,EACd,SAAS,EAAE,OAAO,GACjB,eAAe,CA8DjB"}

package/types/runtime/context.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Trusted authenticated request identity.
+ *
+ * - ActorId: Authenticated actor attributed as the author of record mutations.
+ * - TenantId: Tenant boundary scoping every record operation.
+ *
+ * @group Utils
+ * @category Execution Context
+ */
+export type AuthenticatedContext = Readonly<{
+    actorId: string;
+    tenantId: string;
+}>;
+/**
+ * Per-request tracing metadata.
+ *
+ * - RequestId: Correlation identifier carried through logs for one request or job.
+ *
+ * @group Utils
+ * @category Execution Context
+ */
+export type RequestContext = Readonly<{
+    requestId: string;
+}>;
+/**
+ * Request-scoped execution metadata established by transport middleware.
+ *
+ * - Authenticated: Trusted identity for the current request or job.
+ * - Request: Tracing metadata for the current request or job.
+ *
+ * @remarks
+ * Bound to the async scope by {@link runWithExecutionCtx} and retrieved by
+ * {@link getExecutionCtx}, so downstream policy code such as {@link RecordsHandler} reads the
+ * caller's tenant and actor without threading them through every call.
+ * @group Utils
+ * @category Execution Context
+ */
+export type ExecutionContext = Readonly<{
+    authenticated: AuthenticatedContext;
+    request: RequestContext;
+}>;
+/**
+ * Runs one callback with the supplied execution context bound to the current async scope.
+ *
+ * @remarks
+ * The context is visible to every asynchronous operation started within `callback` and is
+ * torn down when it returns, so nested calls to {@link getExecutionCtx} resolve the same
+ * identity without explicit propagation. Transport middleware wraps request handling in
+ * this call.
+ * @group Utils
+ * @category Execution Context
+ * @param context - Execution context for the current request or job.
+ * @param callback - Work executed while the context is available.
+ * @returns The callback return value.
+ */
+export declare function runWithExecutionCtx<T>(context: ExecutionContext, callback: () => T): T;
+/**
+ * Reads the current execution context.
+ *
+ * @group Utils
+ * @category Execution Context
+ * @returns The active {@link ExecutionContext} for the current async scope.
+ * @throws {CustomError} RESOURCE_NOT_FOUND when called outside a {@link runWithExecutionCtx}
+ *   scope, so no context is bound.
+ */
+export declare function getExecutionCtx(): ExecutionContext;
+//# sourceMappingURL=context.d.ts.map

package/types/runtime/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/runtime/context.ts"],"names":[],"mappings":"AAGA;;;;;;;;GAQG;AACH,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC,CAAC;AAEH;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,GAAG,QAAQ,CAAC;IACpC,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC,CAAC;AAEH;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC;IACtC,aAAa,EAAE,oBAAoB,CAAC;IACpC,OAAO,EAAE,cAAc,CAAC;CACzB,CAAC,CAAC;AAMH;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,CAAC,GAAG,CAAC,CAEtF;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,IAAI,gBAAgB,CAYlD"}

package/types/runtime/index.d.ts

@@ -0,0 +1,2 @@
+export * from './context.js';
+//# sourceMappingURL=index.d.ts.map

package/types/runtime/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/runtime/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC"}

package/types/tokens/access-token-verifier.d.ts

@@ -0,0 +1,36 @@
+import type { IAccessTokenVerifier } from './contracts.js';
+import type { AccessTokenVerifyConfig } from './types.js';
+import type { BearerToken } from './types.js';
+import type { SessionGrant } from './types.js';
+import type { IVerificationKeyProvider } from '../keys/contracts.js';
+/**
+ * Verifies platform access tokens and reconstructs their session grant.
+ *
+ * @remarks
+ * Checks the protected header, resolves the public key by `kid` through the injected
+ * {@link IVerificationKeyProvider}, verifies signature, issuer, audience, and expiry with
+ * `jose`, then parses the claims with {@link accessTokenClaimsSchema}.
+ * @group Tokens
+ * @category Access Tokens
+ */
+export declare class AccessTokenVerifier implements IAccessTokenVerifier {
+    private readonly config;
+    private readonly keys;
+    /**
+     * @param config - Issuer, audience, and clock tolerance every token must satisfy.
+     * @param keys - Source of public verification keys by `kid`.
+     */
+    constructor(config: AccessTokenVerifyConfig, keys: IVerificationKeyProvider);
+    /**
+     * Verifies one bearer access token.
+     *
+     * @param credential - Bearer credential selected by the transport layer.
+     * @returns Trusted session grant read from the token claims.
+     * @throws {CustomError} AUTHENTICATION_FAILED when the token is malformed, signed by an
+     *   unknown key, expired, or carries incomplete claims.
+     * @throws {CustomError} EXTERNAL_API_ERROR or CONFIG_ERROR when the key provider fails;
+     *   propagated unchanged.
+     */
+    verify(credential: BearerToken): Promise<SessionGrant>;
+}
+//# sourceMappingURL=access-token-verifier.d.ts.map

package/types/tokens/access-token-verifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"access-token-verifier.d.ts","sourceRoot":"","sources":["../../src/tokens/access-token-verifier.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAE3D,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAC1D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAErE;;;;;;;;;GASG;AACH,qBAAa,mBAAoB,YAAW,oBAAoB;IAM5D,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,IAAI;IANvB;;;OAGG;gBAEgB,MAAM,EAAE,uBAAuB,EAC/B,IAAI,EAAE,wBAAwB;IAGjD;;;;;;;;;OASG;IACG,MAAM,CAAC,UAAU,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC;CA8C7D"}

package/types/tokens/contracts.d.ts

@@ -0,0 +1,21 @@
+import type { BearerToken, SessionGrant } from './types.js';
+/**
+ * Access-token verification boundary.
+ *
+ * @remarks
+ * {@link AccessTokenVerifier} is the shipped implementation. A consumer injects it behind
+ * this contract, so where the verification keys come from (an owned key set or a remote
+ * JWKS) is chosen at the composition root, not by the consumer.
+ * @group Tokens
+ * @category Access Tokens
+ */
+export interface IAccessTokenVerifier {
+    /**
+     * Verifies one bearer access credential.
+     *
+     * @param credential - Bearer credential selected by the route transport policy.
+     * @returns Trusted session grant reconstructed from the credential.
+     */
+    verify(credential: BearerToken): Promise<SessionGrant>;
+}
+//# sourceMappingURL=contracts.d.ts.map

package/types/tokens/contracts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.d.ts","sourceRoot":"","sources":["../../src/tokens/contracts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE5D;;;;;;;;;GASG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;;OAKG;IACH,MAAM,CAAC,UAAU,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;CACxD"}

package/types/tokens/index.d.ts

@@ -0,0 +1,5 @@
+export * from './access-token-verifier.js';
+export * from './contracts.js';
+export * from './schema.js';
+export * from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/types/tokens/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tokens/index.ts"],"names":[],"mappings":"AAAA,cAAc,4BAA4B,CAAC;AAC3C,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC"}

package/types/tokens/schema.d.ts

@@ -0,0 +1,34 @@
+import { z } from 'zod';
+/**
+ * Access-token verification policy every verifier shares with the issuer.
+ *
+ * - Issuer: Required `iss`, the issuing service's base URL.
+ * - Audience: Required `aud`.
+ * - ClockToleranceSecs: Allowed clock skew when checking `exp` and `iat`.
+ */
+export declare const accessTokenVerifyConfigSchema: z.ZodObject<{
+    issuer: z.ZodURL;
+    audience: z.ZodString;
+    clockToleranceSecs: z.ZodNumber;
+}, z.core.$strict>;
+/**
+ * Platform claims carried by every access token.
+ *
+ * - Sid: Server-side session identifier.
+ * - Sub: Authenticated subject.
+ * - ActorId: Local actor represented by the session.
+ * - TenantId: Tenant the session belongs to.
+ * - Roles: Roles granted to the session.
+ *
+ * @remarks
+ * Not strict: `jwtVerify` already checks the registered claims (`iss`, `aud`, `iat`,
+ * `exp`), and parsing strips them.
+ */
+export declare const accessTokenClaimsSchema: z.ZodObject<{
+    sid: z.ZodString;
+    sub: z.ZodString;
+    actorId: z.ZodString;
+    tenantId: z.ZodString;
+    roles: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+//# sourceMappingURL=schema.d.ts.map

package/types/tokens/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/tokens/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;GAMG;AACH,eAAO,MAAM,6BAA6B;;;;kBAM/B,CAAC;AAEZ;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,uBAAuB;;;;;;iBAMlC,CAAC"}

package/types/tokens/types.d.ts

@@ -0,0 +1,20 @@
+import type { z } from 'zod';
+import type { accessTokenClaimsSchema } from './schema.js';
+import type { accessTokenVerifyConfigSchema } from './schema.js';
+/** Trusted identity reconstructed from a verified access token. */
+export type SessionGrant = Readonly<{
+    sessionId: string;
+    actorId: string;
+    tenantId: string;
+    subject: string;
+    roles: readonly string[];
+}>;
+/** Bearer credential extracted from the HTTP transport. */
+export type BearerToken = Readonly<{
+    token: string;
+}>;
+/** Access-token verification policy every verifier shares with the issuer. */
+export type AccessTokenVerifyConfig = z.infer<typeof accessTokenVerifyConfigSchema>;
+/** Platform claims carried by every access token. */
+export type AccessTokenClaims = z.infer<typeof accessTokenClaimsSchema>;
+//# sourceMappingURL=types.d.ts.map

package/types/tokens/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/tokens/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAC3D,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,aAAa,CAAC;AAEjE,mEAAmE;AACnE,MAAM,MAAM,YAAY,GAAG,QAAQ,CAAC;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1B,CAAC,CAAC;AAEH,2DAA2D;AAC3D,MAAM,MAAM,WAAW,GAAG,QAAQ,CAAC;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAEtD,8EAA8E;AAC9E,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,6BAA6B,CAAC,CAAC;AAEpF,qDAAqD;AACrD,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC"}