@kurdel/auth 0.1.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Andrii Sorokin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,253 @@
+# @kurdel/auth
+
+Storage-agnostic authentication strategies and authorization middleware for
+Kurdel applications.
+
+The package authenticates incoming requests, resolves the current application
+user, and exposes the result through `HttpContext`. Persistence is supplied by
+the application or by adapters such as `@kurdel/auth-db`.
+
+## Installation
+
+```bash
+npm install @kurdel/auth
+```
+
+## Configure authentication
+
+Register one or more named strategies with `AuthModule`. A strategy instance
+can be supplied directly or created from the application container:
+
+```ts
+import { ApiKeyStrategy, AUTH_TOKENS, AuthModule } from '@kurdel/auth';
+
+const auth = new AuthModule({
+  strategies: [
+    {
+      name: 'api-key',
+      useFactory: ioc =>
+        new ApiKeyStrategy({
+          header: 'x-api-key',
+          credentials: ioc.get(AUTH_TOKENS.ApiKeyRepository),
+          users: ioc.get(AUTH_TOKENS.UserRepository),
+          usage: ioc.get(AUTH_TOKENS.ApiKeyUsageRecorder),
+        }),
+    },
+  ],
+});
+```
+
+`AuthModule` registers the authentication middleware automatically. Strategy
+names are application-defined and are referenced by route metadata.
+
+## Protect routes
+
+Set `auth.strategy` to require authentication. Add `roles` when at least one of
+the listed roles is required:
+
+```ts
+import { Controller, Ok, route, type HttpContext } from '@kurdel/core/http';
+
+export class AccountController extends Controller {
+  readonly routes = {
+    profile: route({
+      method: 'GET',
+      path: '/profile',
+      auth: { strategy: 'api-key' },
+    })(this.profile),
+    admin: route({
+      method: 'GET',
+      path: '/admin',
+      auth: { strategy: 'api-key', roles: ['admin'] },
+    })(this.admin),
+    health: route({
+      method: 'GET',
+      path: '/health',
+      auth: { public: true },
+    })(this.health),
+  };
+
+  async profile(ctx: HttpContext) {
+    return Ok({ user: ctx.auth?.user });
+  }
+
+  async admin(ctx: HttpContext) {
+    return Ok({ authenticatedWith: ctx.auth?.strategy });
+  }
+
+  async health() {
+    return Ok({ status: 'up' });
+  }
+}
+```
+
+Controller-level authentication can define defaults for every route. Route
+metadata may override those defaults, and `{ public: true }` makes an
+individual route public.
+
+Authentication failures return `401 Unauthorized`. An authenticated user who
+does not have any required role receives `403 Forbidden`. Referencing an
+unregistered strategy is treated as an application configuration error and
+returns `500 Internal Server Error`.
+
+## Authorization policies
+
+Named policies handle application-specific access rules that cannot be
+expressed by roles alone. Register them alongside strategies:
+
+```ts
+const auth = new AuthModule({
+  strategies: [/* ... */],
+  policies: [
+    {
+      name: 'manage-users',
+      use: {
+        authorize: (auth, ctx) =>
+          auth.credential?.type === 'api-key' &&
+          auth.user.roles.includes('admin') &&
+          ctx.req.method !== 'TRACE',
+      },
+    },
+  ],
+});
+```
+
+Reference policies from route metadata:
+
+```ts
+route({
+  method: 'POST',
+  path: '/users',
+  auth: {
+    strategy: 'api-key',
+    policies: ['manage-users'],
+  },
+})(this.createUser);
+```
+
+A policy receives the complete `AuthContext` and current `HttpContext`, and may
+return a boolean or a promise. When several policies are listed, every policy
+must grant access. Policies and `roles` may be combined; both checks must then
+succeed. A rejected policy returns `403 Forbidden`, while an unknown policy is
+reported as an application configuration error.
+
+Policy providers also support `useFactory`, allowing policies to resolve
+application services from the dependency container.
+
+## Security events
+
+Configure an event sink to observe sanitized authentication and authorization
+activity:
+
+```ts
+new AuthModule({
+  events: {
+    useFactory: ioc => ioc.get(APP_TOKENS.AuthEventSink),
+  },
+  strategies: [/* ... */],
+});
+```
+
+The package reports successful and failed authentication plus authorization
+denials. API-key management services may additionally report credential issue
+and revocation events. Events contain timestamps, strategy names, user and
+credential identifiers, safe reason codes, and policy names. Raw API keys,
+JWTs, credential hashes, headers, and request bodies are never part of the
+event contract.
+
+Without configuration, `AuthModule` uses `NoopAuthEventSink`. Applications may
+provide an instance or a factory-backed sink. Sink failures are propagated so
+operators can choose an appropriate durable or failure-tolerant implementation
+instead of having audit loss silently hidden by the framework.
+
+## Authentication context
+
+After successful authentication, middleware attaches an `AuthContext` to
+`ctx.auth`:
+
+```ts
+interface AuthContext {
+  user: AuthUser;
+  strategy: string;
+  credential?: {
+    type: string;
+    id?: string;
+  };
+  claims?: Record<string, unknown>;
+}
+```
+
+- `user` is the current application identity and its current roles.
+- `strategy` is the registered name selected by route metadata.
+- `credential` identifies the credential kind and, when available, its stable
+  identifier. It never contains the raw API key or JWT.
+- `claims` contains verified strategy-specific claims, such as a JWT payload.
+
+`ctx.user` remains available as an alias of `ctx.auth.user` for compatibility.
+New code that needs authentication metadata should use `ctx.auth`.
+
+The built-in API-key strategy exposes `credential.type` as `api-key` and uses
+the repository credential ID when one exists. The JWT strategy exposes
+`credential.type` as `jwt`, uses the `jti` claim as its optional ID, and places
+the verified payload in `claims`.
+
+## User and credential repositories
+
+Authentication strategies do not own user data. Both built-in strategies load
+the current identity from `AuthUserRepository`, making the repository the
+source of truth for current roles and disabled users:
+
+```ts
+interface AuthUserRepository {
+  findById(id: string | number): Promise<AuthUser | null>;
+}
+```
+
+`ApiKeyStrategy` additionally requires an `ApiKeyRepository`. Its
+implementation must return `null` for unknown credentials and describe known
+credentials without returning their raw secret. Revoked and expired API keys
+are rejected before the user is authenticated.
+
+Applications may provide an `ApiKeyUsageRecorder` to capture successful use of
+credentials with stable IDs. The strategy records usage only after the key is
+accepted and its current user is resolved; rejected, expired, revoked, and
+orphaned credentials are never recorded.
+
+For database-backed implementations, use `@kurdel/auth-db`. Applications may
+also implement these interfaces for another database, an external identity
+service, or an in-memory test setup.
+
+## Custom strategies
+
+Implement `AuthStrategy` to support another authentication mechanism:
+
+```ts
+import type { AuthStrategy, AuthenticationResult } from '@kurdel/auth';
+import type { HttpRequest } from '@kurdel/common';
+
+class SessionStrategy implements AuthStrategy {
+  async authenticate(req: HttpRequest): Promise<AuthenticationResult | null> {
+    const session = await loadSession(req);
+    if (!session) return null;
+
+    return {
+      user: session.user,
+      credential: { type: 'session', id: session.id },
+    };
+  }
+}
+```
+
+A strategy returns `null` when the request cannot be authenticated. On
+success, it returns the user and optional safe credential metadata or verified
+claims. The middleware adds the registered strategy name to the final context.
+
+## Database integration
+
+See [`@kurdel/auth-db`](../auth-db/README.md) for reusable database repository
+adapters and [`sample/auth-db`](../../sample/auth-db/README.md) for a runnable
+SQLite application with API-key authentication and a React administration UI.
+
+## License
+
+MIT © Andrii Sorokin

package/lib/domain/auth-context.d.ts

@@ -0,0 +1,8 @@
+import type { AuthCredential, AuthUser } from '@kurdel/common';
+export type { AuthContext, AuthCredential } from '@kurdel/common';
+/** Data produced by a strategy before middleware attaches the strategy name. */
+export interface AuthenticationResult<TUser extends AuthUser = AuthUser> {
+    user: TUser;
+    credential?: AuthCredential;
+    claims?: Record<string, unknown>;
+}

package/lib/domain/auth-context.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=auth-context.js.map

package/lib/domain/auth-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-context.js","sourceRoot":"","sources":["../../src/domain/auth-context.ts"],"names":[],"mappings":""}

package/lib/domain/auth-event-sink-provider.d.ts

@@ -0,0 +1,7 @@
+import type { Container } from '@kurdel/ioc';
+import type { AuthEventSink } from './auth-event.js';
+export type AuthEventSinkProvider = {
+    use: AuthEventSink;
+} | {
+    useFactory: (container: Container) => AuthEventSink;
+};

package/lib/domain/auth-event-sink-provider.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=auth-event-sink-provider.js.map

package/lib/domain/auth-event-sink-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-event-sink-provider.js","sourceRoot":"","sources":["../../src/domain/auth-event-sink-provider.ts"],"names":[],"mappings":""}

package/lib/domain/auth-event.d.ts

@@ -0,0 +1,30 @@
+import type { AuthCredential, AuthUser } from '@kurdel/common';
+type AuthEventBase = {
+    occurredAt: Date;
+    userId?: AuthUser['id'];
+    credential?: AuthCredential;
+};
+export type AuthEvent = (AuthEventBase & {
+    type: 'authentication.succeeded';
+    strategy: string;
+}) | (AuthEventBase & {
+    type: 'authentication.failed';
+    strategy: string;
+    reason: 'invalid-credential';
+}) | (AuthEventBase & {
+    type: 'authorization.denied';
+    strategy?: string;
+    reason: 'missing-role' | 'missing-authentication' | 'policy-rejected';
+    policy?: string;
+}) | (AuthEventBase & {
+    type: 'api-key.issued' | 'api-key.revoked';
+});
+/** Receives sanitized authentication and authorization lifecycle events. */
+export interface AuthEventSink {
+    report(event: AuthEvent): Promise<void> | void;
+}
+/** Default sink used when an application does not configure event reporting. */
+export declare class NoopAuthEventSink implements AuthEventSink {
+    report(_event: AuthEvent): void;
+}
+export {};

package/lib/domain/auth-event.js

@@ -0,0 +1,5 @@
+/** Default sink used when an application does not configure event reporting. */
+export class NoopAuthEventSink {
+    report(_event) { }
+}
+//# sourceMappingURL=auth-event.js.map

package/lib/domain/auth-event.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-event.js","sourceRoot":"","sources":["../../src/domain/auth-event.ts"],"names":[],"mappings":"AAiCA,gFAAgF;AAChF,MAAM,OAAO,iBAAiB;IAC5B,MAAM,CAAC,MAAiB,IAAS,CAAC;CACnC"}

package/lib/domain/auth-strategy-provider.d.ts

@@ -0,0 +1,9 @@
+import type { Container } from '@kurdel/ioc';
+import type { AuthStrategy } from '../domain/index.js';
+export type AuthStrategyProvider = {
+    name: string;
+    use: AuthStrategy;
+} | {
+    name: string;
+    useFactory: (c: Container) => AuthStrategy;
+};

package/lib/domain/auth-strategy-provider.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=auth-strategy-provider.js.map

package/lib/domain/auth-strategy-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-strategy-provider.js","sourceRoot":"","sources":["../../src/domain/auth-strategy-provider.ts"],"names":[],"mappings":""}

package/lib/domain/auth-strategy.d.ts

@@ -0,0 +1,17 @@
+import type { HttpRequest } from '@kurdel/common';
+import type { AuthenticationResult } from './auth-context.js';
+/**
+ * ## AuthStrategy
+ *
+ * A pluggable authentication mechanism.
+ * Each strategy decides how to extract and validate credentials
+ * from the incoming HTTP request.
+ *
+ * The strategy:
+ *   - returns an AuthenticationResult on success
+ *   - returns null if authentication fails
+ *   - must NOT throw on invalid credentials
+ */
+export interface AuthStrategy {
+    authenticate(req: HttpRequest): Promise<AuthenticationResult | null>;
+}

package/lib/domain/auth-strategy.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=auth-strategy.js.map

package/lib/domain/auth-strategy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-strategy.js","sourceRoot":"","sources":["../../src/domain/auth-strategy.ts"],"names":[],"mappings":""}

package/lib/domain/authorization-policy-provider.d.ts

@@ -0,0 +1,9 @@
+import type { Container } from '@kurdel/ioc';
+import type { AuthorizationPolicy } from './authorization-policy.js';
+export type AuthorizationPolicyProvider = {
+    name: string;
+    use: AuthorizationPolicy;
+} | {
+    name: string;
+    useFactory: (container: Container) => AuthorizationPolicy;
+};

package/lib/domain/authorization-policy-provider.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=authorization-policy-provider.js.map

package/lib/domain/authorization-policy-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"authorization-policy-provider.js","sourceRoot":"","sources":["../../src/domain/authorization-policy-provider.ts"],"names":[],"mappings":""}

package/lib/domain/authorization-policy.d.ts

@@ -0,0 +1,6 @@
+import type { AuthContext } from '@kurdel/common';
+import type { HttpContext } from '@kurdel/core/http';
+/** Performs an application-specific authorization check for a request. */
+export interface AuthorizationPolicy {
+    authorize(auth: Readonly<AuthContext>, ctx: HttpContext): boolean | Promise<boolean>;
+}

package/lib/domain/authorization-policy.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=authorization-policy.js.map

package/lib/domain/authorization-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"authorization-policy.js","sourceRoot":"","sources":["../../src/domain/authorization-policy.ts"],"names":[],"mappings":""}

package/lib/domain/index.d.ts

@@ -0,0 +1,7 @@
+export * from './auth-context.js';
+export * from './auth-event.js';
+export * from './auth-event-sink-provider.js';
+export * from './auth-strategy-provider.js';
+export * from './auth-strategy.js';
+export * from './authorization-policy.js';
+export * from './authorization-policy-provider.js';

package/lib/domain/index.js

@@ -0,0 +1,8 @@
+export * from './auth-context.js';
+export * from './auth-event.js';
+export * from './auth-event-sink-provider.js';
+export * from './auth-strategy-provider.js';
+export * from './auth-strategy.js';
+export * from './authorization-policy.js';
+export * from './authorization-policy-provider.js';
+//# sourceMappingURL=index.js.map

package/lib/domain/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/domain/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,oBAAoB,CAAC;AACnC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,oCAAoC,CAAC"}

package/lib/index.d.ts

@@ -0,0 +1,6 @@
+export * from './domain/index.js';
+export * from './infra/index.js';
+export * from './repositories/index.js';
+export * from './runtime/index.js';
+export * from './strategies/index.js';
+export * from './tokens.js';

package/lib/index.js

@@ -0,0 +1,7 @@
+export * from './domain/index.js';
+export * from './infra/index.js';
+export * from './repositories/index.js';
+export * from './runtime/index.js';
+export * from './strategies/index.js';
+export * from './tokens.js';
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,yBAAyB,CAAA;AACvC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAA;AACrC,cAAc,aAAa,CAAA"}

package/lib/infra/in-memory/in-memory-api-key-repository.d.ts

@@ -0,0 +1,7 @@
+import type { ApiKeyCredential, ApiKeyRepository } from '../../repositories/index.js';
+/** In-memory credential source intended for tests, demos and bootstrap code. */
+export declare class InMemoryApiKeyRepository implements ApiKeyRepository {
+    private readonly keys;
+    constructor(keys: Record<string, ApiKeyCredential>);
+    findByKey(key: string): ApiKeyCredential | null;
+}

package/lib/infra/in-memory/in-memory-api-key-repository.js

@@ -0,0 +1,10 @@
+/** In-memory credential source intended for tests, demos and bootstrap code. */
+export class InMemoryApiKeyRepository {
+    constructor(keys) {
+        this.keys = keys;
+    }
+    findByKey(key) {
+        return this.keys[key] ?? null;
+    }
+}
+//# sourceMappingURL=in-memory-api-key-repository.js.map

package/lib/infra/in-memory/in-memory-api-key-repository.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"in-memory-api-key-repository.js","sourceRoot":"","sources":["../../../src/infra/in-memory/in-memory-api-key-repository.ts"],"names":[],"mappings":"AAEA,gFAAgF;AAChF,MAAM,OAAO,wBAAwB;IACnC,YAA6B,IAAsC;QAAtC,SAAI,GAAJ,IAAI,CAAkC;IAAG,CAAC;IAEvE,SAAS,CAAC,GAAW;QACnB,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC;IAChC,CAAC;CACF"}

package/lib/infra/in-memory/in-memory-auth-user-repository.d.ts

@@ -0,0 +1,8 @@
+import type { AuthUser } from '@kurdel/common';
+import type { AuthUserRepository } from '../../repositories/index.js';
+/** In-memory identity source intended for tests, demos and bootstrap code. */
+export declare class InMemoryAuthUserRepository implements AuthUserRepository {
+    private readonly users;
+    constructor(users: AuthUser[]);
+    findById(id: string | number): AuthUser | null;
+}

package/lib/infra/in-memory/in-memory-auth-user-repository.js

@@ -0,0 +1,10 @@
+/** In-memory identity source intended for tests, demos and bootstrap code. */
+export class InMemoryAuthUserRepository {
+    constructor(users) {
+        this.users = users;
+    }
+    findById(id) {
+        return this.users.find(user => user.id === id) ?? null;
+    }
+}
+//# sourceMappingURL=in-memory-auth-user-repository.js.map

package/lib/infra/in-memory/in-memory-auth-user-repository.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"in-memory-auth-user-repository.js","sourceRoot":"","sources":["../../../src/infra/in-memory/in-memory-auth-user-repository.ts"],"names":[],"mappings":"AAIA,8EAA8E;AAC9E,MAAM,OAAO,0BAA0B;IACrC,YAA6B,KAAiB;QAAjB,UAAK,GAAL,KAAK,CAAY;IAAG,CAAC;IAElD,QAAQ,CAAC,EAAmB;QAC1B,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,CAAC,IAAI,IAAI,CAAC;IACzD,CAAC;CACF"}

package/lib/infra/in-memory/in-memory-jwt-repository.d.ts

@@ -0,0 +1,7 @@
+import type { AuthUser } from '@kurdel/common';
+import type { JwtRepository } from '../../repositories/index.js';
+import { InMemoryAuthUserRepository } from './in-memory-auth-user-repository.js';
+/** @deprecated Use InMemoryAuthUserRepository. */
+export declare class InMemoryJwtRepository extends InMemoryAuthUserRepository implements JwtRepository {
+    constructor(users: AuthUser[]);
+}

package/lib/infra/in-memory/in-memory-jwt-repository.js

@@ -0,0 +1,8 @@
+import { InMemoryAuthUserRepository } from './in-memory-auth-user-repository.js';
+/** @deprecated Use InMemoryAuthUserRepository. */
+export class InMemoryJwtRepository extends InMemoryAuthUserRepository {
+    constructor(users) {
+        super(users);
+    }
+}
+//# sourceMappingURL=in-memory-jwt-repository.js.map

package/lib/infra/in-memory/in-memory-jwt-repository.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"in-memory-jwt-repository.js","sourceRoot":"","sources":["../../../src/infra/in-memory/in-memory-jwt-repository.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,0BAA0B,EAAE,MAAM,qCAAqC,CAAC;AAEjF,kDAAkD;AAClD,MAAM,OAAO,qBACX,SAAQ,0BAA0B;IAElC,YAAY,KAAiB;QAC3B,KAAK,CAAC,KAAK,CAAC,CAAC;IACf,CAAC;CACF"}

package/lib/infra/in-memory/index.d.ts

@@ -0,0 +1,3 @@
+export * from './in-memory-api-key-repository.js';
+export * from './in-memory-auth-user-repository.js';
+export * from './in-memory-jwt-repository.js';

package/lib/infra/in-memory/index.js

@@ -0,0 +1,4 @@
+export * from './in-memory-api-key-repository.js';
+export * from './in-memory-auth-user-repository.js';
+export * from './in-memory-jwt-repository.js';
+//# sourceMappingURL=index.js.map

package/lib/infra/in-memory/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/infra/in-memory/index.ts"],"names":[],"mappings":"AAAA,cAAc,mCAAmC,CAAC;AAClD,cAAc,qCAAqC,CAAC;AACpD,cAAc,+BAA+B,CAAC"}

package/lib/infra/index.d.ts

@@ -0,0 +1 @@
+export * from './in-memory/index.js';

package/lib/infra/index.js

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

package/lib/infra/index.js.map

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

package/lib/repositories/api-key/api-key-repository.d.ts

@@ -0,0 +1,30 @@
+export interface ApiKeyCredential {
+    /** Stable credential identifier, when the backing store exposes one. */
+    id?: string;
+    /** Stable identity resolved after credential validation. */
+    userId: string | number;
+    /** Revoked credentials must never authenticate. */
+    revoked?: boolean;
+    /** Optional absolute expiry time. */
+    expiresAt?: Date;
+}
+/**
+ * ## ApiKeyRepository
+ *
+ * Abstraction for retrieving credential metadata by API key.
+ *
+ * A repository implementation may:
+ * - load records from an in-memory map
+ * - query a database
+ * - read from Redis or any other KV store
+ * - call an external authentication service
+ *
+ * Strategies depend only on this interface, not on the storage details.
+ */
+export interface ApiKeyRepository {
+    /**
+     * Returns credential metadata associated with the given API key.
+     * If the key is unknown, must return `null`.
+     */
+    findByKey(key: string): Promise<ApiKeyCredential | null> | ApiKeyCredential | null;
+}

package/lib/repositories/api-key/api-key-repository.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=api-key-repository.js.map

package/lib/repositories/api-key/api-key-repository.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-key-repository.js","sourceRoot":"","sources":["../../../src/repositories/api-key/api-key-repository.ts"],"names":[],"mappings":""}

package/lib/repositories/api-key/api-key-usage-recorder.d.ts

@@ -0,0 +1,4 @@
+/** Persists successful API-key usage without coupling strategies to storage. */
+export interface ApiKeyUsageRecorder {
+    recordUsage(credentialId: string, usedAt: Date): Promise<void> | void;
+}

package/lib/repositories/api-key/api-key-usage-recorder.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=api-key-usage-recorder.js.map

package/lib/repositories/api-key/api-key-usage-recorder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-key-usage-recorder.js","sourceRoot":"","sources":["../../../src/repositories/api-key/api-key-usage-recorder.ts"],"names":[],"mappings":""}

package/lib/repositories/api-key/index.d.ts

@@ -0,0 +1,2 @@
+export * from './api-key-repository.js';
+export * from './api-key-usage-recorder.js';

package/lib/repositories/api-key/index.js

@@ -0,0 +1,3 @@
+export * from './api-key-repository.js';
+export * from './api-key-usage-recorder.js';
+//# sourceMappingURL=index.js.map

package/lib/repositories/api-key/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/repositories/api-key/index.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAC;AACxC,cAAc,6BAA6B,CAAC"}

package/lib/repositories/index.d.ts

@@ -0,0 +1,3 @@
+export * from './api-key/index.js';
+export * from './jwt/index.js';
+export * from './user/index.js';