@dereekb/firebase-server 14.4.0 → 14.5.1

package/oidc/src/lib/service/oidc.config.service.d.ts

@@ -90,9 +90,14 @@ export declare class OidcProviderConfigService {
      * provider does support those scopes, for the clients holding the profile. This narrower list is
      * for metadata a client treats as a request template — notably an MCP protected-resource
      * document's `scopes_supported`, which dynamic-registration clients (the Claude Code CLI) copy
-     * verbatim onto `/authorize`. An assignment-only scope advertised there ends the flow in
-     * `access_denied`: the consent unlock gate judges the REQUEST, so unlike an admin-only scope
-     * there is no deselect-at-consent way through.
+     * verbatim onto `/authorize`. Defaulting such a document to this narrower list keeps an
+     * unassigned client from requesting a scope it can never be granted.
+     *
+     * A resource MAY still advertise an assignment-only scope deliberately (demo-api does for
+     * `token.cli`, so an MCP connector can ask for it at all). That is not fatal for the clients
+     * lacking the profile: the consent URL builder withholds the scope from them, so it lands in the
+     * submit's `rejected` set and the flow completes without it — the same treatment an admin-only
+     * scope gets for a non-admin.
      */
     readonly clientRequestableScopesSupported: string[];
     /**

package/oidc/src/lib/service/oidc.download-signer.d.ts

@@ -0,0 +1,17 @@
+import { type DownloadTokenSigner } from '@dereekb/firebase-server';
+import { type OidcJwtSigningService } from './oidc.jwt-signing.service';
+/**
+ * Adapts {@link OidcJwtSigningService} to the `@dereekb/firebase-server` {@link DownloadTokenSigner}
+ * interface, so the signed asset-download endpoint can use the OIDC provider's own JWKS without
+ * `@dereekb/firebase-server` taking a dependency on this package.
+ *
+ * Using the provider's JWKS is the point: it is already shared across function instances and already
+ * rotates, so a download capability token needs no new secret to distribute. The `typ` + `aud`
+ * discriminators the download module passes in are what keep such a token from ever being accepted
+ * as an OAuth access token (and vice versa) even though both are signed by the same keys.
+ *
+ * @param signingService - The provider's JWT signing service.
+ * @returns A signer to register under the `DOWNLOAD_TOKEN_SIGNER` injection token.
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function oidcDownloadTokenSigner(signingService: OidcJwtSigningService): DownloadTokenSigner;

package/oidc/src/lib/service/oidc.jwt-signing.service.d.ts

@@ -1,4 +1,5 @@
 import { type Maybe, type Milliseconds, type Seconds } from '@dereekb/util';
+import { type JWTPayload } from 'jose';
 import { OidcModuleConfig } from '../oidc.config';
 import { JwksService } from './oidc.jwks.service';
 /**
@@ -39,6 +40,23 @@ export interface OidcSignJwtInput {
      */
     readonly typ?: Maybe<string>;
 }
+export interface OidcVerifyJwtInput {
+    /**
+     * The compact JWT to verify.
+     */
+    readonly token: string;
+    /**
+     * Required `aud` claim value.
+     */
+    readonly audience: string | readonly string[];
+    /**
+     * Required header `typ`. Pass the SAME discriminator the token was minted with — a first-party JWT
+     * minted for a non-OAuth purpose (e.g. an asset-download capability) is signed by the same JWKS as
+     * the provider's `at+jwt` access tokens, so `typ` + `aud` are what keep the two from being
+     * interchangeable.
+     */
+    readonly typ?: Maybe<string>;
+}
 export interface OidcSignedJwt {
     readonly token: string;
     readonly expiresAt: Date;
@@ -65,6 +83,7 @@ export declare class OidcJwtSigningService {
     private readonly _jwks;
     private readonly _config;
     private _cached;
+    private _verifyKey;
     constructor(_jwks: JwksService, _config: OidcModuleConfig);
     /**
      * Mints a signed JWT.
@@ -73,5 +92,21 @@ export declare class OidcJwtSigningService {
      * @returns The compact token, its expiry, and the signing key id.
      */
     signJwt(input: OidcSignJwtInput): Promise<OidcSignedJwt>;
+    /**
+     * Verifies a JWT that THIS provider signed, against its own JWKS.
+     *
+     * Enforces `iss` (this provider), `aud`, and — when supplied — the header `typ`. Returns
+     * `undefined` rather than throwing when the token does not verify, so a caller serving an
+     * unauthenticated route can answer with one generic error for every failure mode.
+     *
+     * The counterpart to {@link signJwt}: `verifyAccessToken` deliberately does NOT accept a token
+     * minted with a non-`at+jwt` `typ` and a non-OAuth audience, and this method is how a purpose-built
+     * token proves it is the RIGHT kind.
+     *
+     * @param input - The token, its required audience, and its required `typ`.
+     * @returns The verified payload, or `undefined` when verification fails.
+     */
+    verifyJwt(input: OidcVerifyJwtInput): Promise<Maybe<JWTPayload>>;
+    private _getVerifyKey;
     private _loadSigningKey;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/firebase-server",
-  "version": "14.4.0",
+  "version": "14.5.1",
   "type": "module",
   "sideEffects": false,
   "exports": {
@@ -58,18 +58,18 @@
   },
   "peerDependencies": {
     "@cantoo/pdf-lib": ">=2.6.5 <2.11.0",
-    "@dereekb/analytics": "14.4.0",
-    "@dereekb/calcom": "14.4.0",
-    "@dereekb/date": "14.4.0",
-    "@dereekb/dbx-core": "14.4.0",
-    "@dereekb/discord": "14.4.0",
-    "@dereekb/firebase": "14.4.0",
-    "@dereekb/model": "14.4.0",
-    "@dereekb/nestjs": "14.4.0",
-    "@dereekb/oauth-resource": "14.4.0",
-    "@dereekb/rxjs": "14.4.0",
-    "@dereekb/util": "14.4.0",
-    "@dereekb/zoho": "14.4.0",
+    "@dereekb/analytics": "14.5.1",
+    "@dereekb/calcom": "14.5.1",
+    "@dereekb/date": "14.5.1",
+    "@dereekb/dbx-core": "14.5.1",
+    "@dereekb/discord": "14.5.1",
+    "@dereekb/firebase": "14.5.1",
+    "@dereekb/model": "14.5.1",
+    "@dereekb/nestjs": "14.5.1",
+    "@dereekb/oauth-resource": "14.5.1",
+    "@dereekb/rxjs": "14.5.1",
+    "@dereekb/util": "14.5.1",
+    "@dereekb/zoho": "14.5.1",
     "@google-cloud/firestore": "^7.11.6",
     "@google-cloud/storage": "^7.22.0",
     "@modelcontextprotocol/node": "2.0.0",

package/src/lib/nest/controller/download/download.api.config.d.ts

@@ -0,0 +1,203 @@
+import { type Maybe, type Seconds, type WebsiteUrl } from '@dereekb/util';
+/**
+ * Route prefix the download controller is mounted at. Under the `/api` global route prefix the route
+ * becomes `GET /api/download`.
+ */
+export declare const DOWNLOAD_API_ROUTE_PREFIX = "download";
+/**
+ * Path (relative to the API base URL) of the signed asset-download endpoint.
+ */
+export declare const DOWNLOAD_API_PATH = "/download";
+/**
+ * Query parameter carrying the signed capability token.
+ */
+export declare const DOWNLOAD_API_ASSET_QUERY_PARAM = "asset";
+/**
+ * Folder, relative to the app's dist output, that holds every mintable asset.
+ *
+ * The downloadable set is exactly this ONE folder — nothing outside it is ever mintable, and the
+ * containment check in {@link resolveSecureAssetPath} is what enforces that.
+ */
+export declare const DEFAULT_SECURE_ASSETS_DIRECTORY = "assets/secure";
+/**
+ * `aud` claim of a download capability token.
+ *
+ * Distinct from every OAuth audience so a download token can never be presented as a bearer access
+ * token — `oidcProviderIssuerProfiles` only accepts the registered resource-server audiences and the
+ * issuer itself.
+ */
+export declare const DOWNLOAD_TOKEN_AUDIENCE = "dbx:asset-download";
+/**
+ * Header `typ` of a download capability token.
+ *
+ * **Load-bearing.** The same JWKS signs the provider's `at+jwt` access tokens, so this is the second
+ * half of the mutual rejection: the download verifier accepts ONLY this `typ` (plus
+ * {@link DOWNLOAD_TOKEN_AUDIENCE}), and the bearer path rejects a download token on its audience.
+ */
+export declare const DOWNLOAD_TOKEN_TYP = "dbx-dl+jwt";
+/**
+ * `sub` claim of a download capability token. The token carries NO user identifier — the caller is
+ * authorized at MINT time and the uid goes to the audit log there, so it never lands in a URL that
+ * ends up in shell history and proxy logs.
+ */
+export declare const DOWNLOAD_TOKEN_SUBJECT = "dbx:asset";
+/**
+ * Claim carrying the asset path, RELATIVE to the secure root. Never absolute.
+ */
+export declare const DOWNLOAD_TOKEN_PATH_CLAIM = "p";
+/**
+ * Default lifetime of a minted download URL.
+ */
+export declare const DEFAULT_DOWNLOAD_TOKEN_TTL_SECONDS: Seconds;
+/**
+ * Ceiling on a minted download URL's lifetime.
+ *
+ * A download URL is deliberately NOT one-time — a network blip partway through a multi-megabyte
+ * download would otherwise burn it — so the TTL is the whole control, with the token's `jti` logged
+ * so a replay is at least visible.
+ */
+export declare const MAX_DOWNLOAD_TOKEN_TTL_SECONDS: Seconds;
+/**
+ * The verified claims of a download capability token.
+ */
+export interface DownloadTokenClaims {
+    /**
+     * The asset path, relative to the secure root.
+     */
+    readonly path: string;
+    /**
+     * The token's unique id, logged so a replay is visible.
+     */
+    readonly jti?: string;
+}
+/**
+ * Input to {@link DownloadTokenSigner.signToken}.
+ */
+export interface DownloadTokenSignInput {
+    readonly claims: Record<string, unknown>;
+    readonly audience: string;
+    readonly subject: string;
+    readonly typ: string;
+    readonly expiresIn: Seconds;
+}
+/**
+ * Result of {@link DownloadTokenSigner.signToken}.
+ */
+export interface DownloadTokenSignResult {
+    readonly token: string;
+    readonly expiresAt: Date;
+}
+/**
+ * Input to {@link DownloadTokenSigner.verifyToken}.
+ */
+export interface DownloadTokenVerifyInput {
+    readonly token: string;
+    readonly audience: string;
+    readonly typ: string;
+}
+/**
+ * App-supplied JWT signer/verifier backing the download capability token.
+ *
+ * Kept as an interface so `@dereekb/firebase-server` takes no dependency on the OIDC package: the
+ * app adapts `OidcJwtSigningService` (whose keys are the provider's own already-rotating JWKS, so
+ * there is no new secret to distribute). Nothing outside the download module knows how the token is
+ * BUILT — the signer only signs and verifies whatever claims it is handed.
+ *
+ * Without a signer the endpoint fails closed and no URL can be minted.
+ */
+export interface DownloadTokenSigner {
+    signToken(input: DownloadTokenSignInput): Promise<DownloadTokenSignResult>;
+    /**
+     * Verifies a token, returning its claims, or `undefined` when it is not a valid token of this
+     * `typ` + `audience` from this issuer.
+     */
+    verifyToken(input: DownloadTokenVerifyInput): Promise<Maybe<Record<string, unknown>>>;
+}
+/**
+ * NestJS injection token for the {@link DownloadTokenSigner} provider.
+ */
+export declare const DOWNLOAD_TOKEN_SIGNER = "DOWNLOAD_TOKEN_SIGNER";
+/**
+ * Configuration for the signed asset-download endpoint, supplied by the app via its dependency module.
+ *
+ * Without a resolvable {@link secureAssetsRoot} the endpoint fails closed for every request.
+ */
+export declare abstract class DownloadApiModuleConfig {
+    /**
+     * Absolute path to the ONLY folder assets may be served from.
+     *
+     * Resolve it with the same three-cwd probe the dist manifests use — the Functions runtime, a
+     * workspace-root run, and vitest all set different `process.cwd()` values.
+     */
+    readonly secureAssetsRoot?: Maybe<string>;
+    /**
+     * The app's API base URL, used to build the absolute minted URL.
+     */
+    readonly apiBaseUrl?: Maybe<WebsiteUrl>;
+    /**
+     * Default lifetime for a minted URL. Clamped to {@link MAX_DOWNLOAD_TOKEN_TTL_SECONDS}. Defaults to
+     * {@link DEFAULT_DOWNLOAD_TOKEN_TTL_SECONDS}.
+     */
+    readonly defaultTtlSeconds?: Maybe<Seconds>;
+}
+/**
+ * Resolves an asset path, relative to the secure root, to the absolute file it names — or
+ * `undefined` when it escapes containment.
+ *
+ * **This function IS the security model for Part C.** With a folder root rather than a key registry,
+ * a mistake here is an arbitrary-file-read primitive on the function's filesystem, so it is enforced
+ * in BOTH places (at mint, so a URL for an outside file can never be obtained; and at download, so a
+ * bug in the minting path cannot become a read primitive) and both call sites share this one
+ * function so they cannot drift.
+ *
+ * Rejected up front: an absolute path, any `..` segment, a null byte, and an empty path. Then
+ * `realpath` is applied to BOTH sides — that is what stops a symlink inside `secure/` from pointing
+ * at `/etc` or at the function's `.env`. The final containment compare appends `path.sep` so a
+ * sibling directory sharing a name prefix (`secure-other/x`) cannot pass a naive `startsWith`.
+ *
+ * @param secureRoot - Absolute path to the secure root folder, or `undefined` when unconfigured (⇒ always fails).
+ * @param relativePath - The asset path relative to the secure root.
+ * @returns The absolute, real path of the file, or `undefined` when it is not a contained regular file.
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function resolveSecureAssetPath(secureRoot: Maybe<string>, relativePath: Maybe<string>): Maybe<string>;
+/**
+ * Returns true when a relative asset path is structurally safe to resolve — non-empty, relative, free
+ * of `..` segments, and free of null bytes.
+ *
+ * Split out from {@link resolveSecureAssetPath} so the structural rejection is testable without a
+ * filesystem, and so the reason a path is refused is one check rather than a compound condition.
+ *
+ * @param relativePath - The candidate path.
+ * @returns True when the path may be resolved against the secure root.
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function isSafeRelativeAssetPath(relativePath: string): boolean;
+/**
+ * Clamps a requested download-URL lifetime to {@link MAX_DOWNLOAD_TOKEN_TTL_SECONDS}.
+ *
+ * @param requestedTtlSeconds - The requested lifetime, if any.
+ * @param defaultTtlSeconds - The app-configured default, used when none is requested.
+ * @returns The lifetime to sign with, in seconds.
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function downloadTokenTtlSeconds(requestedTtlSeconds: Maybe<Seconds>, defaultTtlSeconds?: Maybe<Seconds>): Seconds;
+/**
+ * File-extension to `Content-Type` table for served assets.
+ *
+ * Intentionally tiny: the secure root holds build artifacts, and anything unrecognized is served as
+ * {@link DEFAULT_DOWNLOAD_CONTENT_TYPE} rather than being guessed at.
+ */
+export declare const DOWNLOAD_CONTENT_TYPES: Readonly<Record<string, string>>;
+/**
+ * `Content-Type` used for any asset whose extension is not in {@link DOWNLOAD_CONTENT_TYPES}.
+ */
+export declare const DEFAULT_DOWNLOAD_CONTENT_TYPE = "application/octet-stream";
+/**
+ * Resolves the `Content-Type` for a file path from its extension.
+ *
+ * @param filePath - The resolved file path.
+ * @returns The content type, defaulting to {@link DEFAULT_DOWNLOAD_CONTENT_TYPE}.
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function downloadContentTypeForPath(filePath: string): string;

package/src/lib/nest/controller/download/download.api.controller.d.ts

@@ -0,0 +1,25 @@
+import { type Response } from 'express';
+import { DownloadApiService } from './download.api.service';
+/**
+ * REST controller that streams one registered asset to whoever holds a valid signed URL.
+ *
+ * Mounted at `download` — under the `/api` global prefix the route becomes `GET /api/download`.
+ *
+ * `/api/download` must **NOT** be listed in the OIDC module's `protectedPaths`: it authenticates via
+ * the signed `asset` query parameter, and a bearer middleware in front of it would 401 exactly the
+ * callers the feature exists for (a bare machine that has no credential yet — obtaining one is the
+ * whole point). Do not "fix" that by adding it.
+ *
+ * Follows `McpController`'s `@Res()` style; there is no `StreamableFile` precedent in this repo.
+ */
+export declare class DownloadApiController {
+    private readonly downloadService;
+    constructor(downloadService: DownloadApiService);
+    /**
+     * Streams the asset named by a signed capability token.
+     *
+     * @param asset - The signed token from the `asset` query parameter.
+     * @param res - The Express response the file is streamed to.
+     */
+    downloadAsset(asset: string, res: Response): Promise<void>;
+}

package/src/lib/nest/controller/download/download.api.module.d.ts

@@ -0,0 +1,47 @@
+import { type ModuleMetadata } from '@nestjs/common';
+import { type ClassType } from '@dereekb/util';
+/**
+ * Configuration for {@link downloadApiModuleMetadata}.
+ */
+export interface DownloadApiModuleMetadataConfig extends Pick<ModuleMetadata, 'imports' | 'exports' | 'providers'> {
+    /**
+     * Module that exports the download endpoint's dependencies.
+     *
+     * Should provide:
+     * - {@link DownloadApiModuleConfig} — the absolute secure-assets root and the API base URL. Without
+     *   a resolvable root every request fails closed.
+     * - `DOWNLOAD_TOKEN_SIGNER` — the app's JWT signer/verifier, typically adapting
+     *   `OidcJwtSigningService` so the provider's own JWKS signs the capability tokens.
+     */
+    readonly dependencyModule: ClassType;
+}
+/**
+ * Generates NestJS module metadata for the signed asset-download API.
+ *
+ * Mirrors `sessionApiModuleMetadata`: the consumer provides a dependency module exposing the
+ * required tokens and this factory wires the controller + service.
+ *
+ * Do NOT add `'/api/download'` to the OIDC module's `protectedPaths` — the route authenticates via
+ * its signed `asset` query parameter, and a bearer middleware would 401 the very callers it exists
+ * for.
+ *
+ * @param metadataConfig - Configuration including the dependency module.
+ * @returns NestJS module metadata exposing the download controller + service.
+ *
+ * @example
+ * ```typescript
+ * @Module({
+ *   imports: [MyOidcModule],
+ *   providers: [
+ *     { provide: DownloadApiModuleConfig, useValue: { secureAssetsRoot, apiBaseUrl } },
+ *     { provide: DOWNLOAD_TOKEN_SIGNER, useFactory: oidcDownloadTokenSignerFactory, inject: [OidcJwtSigningService] }
+ *   ],
+ *   exports: [DownloadApiModuleConfig, DOWNLOAD_TOKEN_SIGNER]
+ * })
+ * export class MyDownloadDependencyModule {}
+ *
+ * @Module(downloadApiModuleMetadata({ dependencyModule: MyDownloadDependencyModule }))
+ * export class MyDownloadApiModule {}
+ * ```
+ */
+export declare function downloadApiModuleMetadata(metadataConfig: DownloadApiModuleMetadataConfig): ModuleMetadata;

package/src/lib/nest/controller/download/download.api.service.d.ts

@@ -0,0 +1,111 @@
+import { type Readable } from 'node:stream';
+import { type ISO8601DateString, type Maybe, type Seconds, type WebsiteUrl } from '@dereekb/util';
+import { DownloadApiModuleConfig, type DownloadTokenSigner } from './download.api.config';
+/**
+ * Error code returned when the `asset` token is missing, malformed, or not a valid download token.
+ */
+export declare const DOWNLOAD_INVALID_TOKEN_ERROR_CODE = "DOWNLOAD_INVALID_TOKEN_ERROR";
+/**
+ * Error code returned when the token verifies but names nothing servable — a missing file, a
+ * directory, or anything that fails containment. Deliberately one code for all three so the endpoint
+ * does not report whether a given path exists outside the secure root.
+ */
+export declare const DOWNLOAD_ASSET_NOT_FOUND_ERROR_CODE = "DOWNLOAD_ASSET_NOT_FOUND_ERROR";
+/**
+ * Error code returned when minting is asked for an asset that is not inside the secure root.
+ */
+export declare const DOWNLOAD_ASSET_NOT_MINTABLE_ERROR_CODE = "DOWNLOAD_ASSET_NOT_MINTABLE_ERROR";
+/**
+ * Input to {@link DownloadApiService.downloadUrlForAsset}.
+ */
+export interface DownloadUrlForAssetInput {
+    /**
+     * The asset path RELATIVE to the secure root, e.g. `demo-cli`.
+     */
+    readonly path: string;
+    /**
+     * Optional lifetime in seconds. Clamped to one hour.
+     */
+    readonly ttlSeconds?: Maybe<Seconds>;
+    /**
+     * Optional uid of the caller the URL is being minted for, written to the audit log. NOT put in the
+     * token — a download URL lands in shell history and proxy logs.
+     */
+    readonly forUid?: Maybe<string>;
+}
+/**
+ * A minted download URL.
+ */
+export interface DownloadUrlForAssetResult {
+    readonly url: WebsiteUrl;
+    readonly expiresAt: ISO8601DateString;
+    /**
+     * SHA-256 of the artifact, so the caller can verify what it fetched.
+     */
+    readonly sha256: string;
+    /**
+     * Size of the artifact in bytes.
+     */
+    readonly size: number;
+}
+/**
+ * A resolved, contained asset ready to be streamed.
+ */
+export interface ResolvedDownloadAsset {
+    readonly absolutePath: string;
+    readonly fileName: string;
+    readonly contentType: string;
+    readonly size: number;
+    readonly stream: () => Readable;
+}
+/**
+ * Mints and resolves signed, self-authenticating asset-download URLs.
+ *
+ * A minted URL is a capability: anything holding it can fetch exactly one file until it expires. The
+ * downloadable set is ONE folder (the app's configured secure root) and the containment check in
+ * `resolveSecureAssetPath` runs on BOTH sides — refusing to sign a token for anything outside the
+ * root, and refusing to serve one even if a signed token somehow names an outside path.
+ *
+ * The token is signed with the OIDC provider's own JWKS through an app-supplied
+ * {@link DownloadTokenSigner}, so it needs no new secret and rotates with the provider's keys. Its
+ * `typ` (`dbx-dl+jwt`) and `aud` (`dbx:asset-download`) are load-bearing discriminators: the bearer
+ * middleware must never accept a download token, and this verifier must never accept an access token.
+ */
+export declare class DownloadApiService {
+    private readonly config?;
+    private readonly signer?;
+    private readonly _logger;
+    constructor(config?: DownloadApiModuleConfig | undefined, signer?: DownloadTokenSigner | undefined);
+    /**
+     * Whether the download path is usable at all (a signer AND a secure root are configured).
+     */
+    get enabled(): boolean;
+    /**
+     * Mints a signed, self-authenticating URL for one asset inside the secure root.
+     *
+     * @param input - The asset path, optional TTL, and the minting caller's uid (for the audit log only).
+     * @returns The absolute URL, its expiry, and the artifact's SHA-256 + size.
+     * @throws {HttpsError} A `400` when the path is not a servable file inside the secure root, or when the endpoint is not configured.
+     */
+    downloadUrlForAsset(input: DownloadUrlForAssetInput): Promise<DownloadUrlForAssetResult>;
+    /**
+     * Verifies a download token and resolves the asset it names, re-running containment.
+     *
+     * @param rawToken - The raw `asset` query parameter.
+     * @returns The resolved asset, ready to stream.
+     * @throws {HttpsError} A `401` for a missing/invalid/expired token, or a `404` for anything not servable.
+     */
+    resolveDownloadRequest(rawToken: Maybe<string>): Promise<ResolvedDownloadAsset>;
+    private _invalidTokenError;
+    private _notFoundError;
+}
+/**
+ * Computes the SHA-256 of a file, hex-encoded.
+ *
+ * Read fully into memory rather than streamed: the secure root holds build artifacts in the tens of
+ * megabytes at most, and the hash is only computed at mint time (not per download).
+ *
+ * @param absolutePath - The absolute path to hash.
+ * @returns The lowercase hex digest.
+ */
+export declare function sha256ForFile(absolutePath: string): string;

package/src/lib/nest/controller/download/index.d.ts

@@ -0,0 +1,4 @@
+export * from './download.api.config';
+export * from './download.api.service';
+export * from './download.api.controller';
+export * from './download.api.module';

package/src/lib/nest/controller/index.d.ts

@@ -1,4 +1,6 @@
 export * from './auth.context.server';
 export * from './api.scope';
+export * from './request.ip';
+export * from './download';
 export * from './model';
 export * from './session';

package/src/lib/nest/controller/request.ip.d.ts

@@ -0,0 +1,60 @@
+import { type Maybe } from '@dereekb/util';
+/**
+ * Header carrying the originating client address through a proxy chain, as a comma-delimited list
+ * whose FIRST entry is the original caller.
+ *
+ * Cloud Run / Cloud Functions sit behind Google's front end, which always rewrites this header, so
+ * the leftmost value is trustworthy there. Behind an arbitrary reverse proxy it is caller-controlled
+ * — see {@link requestClientIp}'s note on what this address may and may not be used for.
+ */
+export declare const FORWARDED_FOR_REQUEST_HEADER = "x-forwarded-for";
+/**
+ * The minimal request shape {@link requestClientIp} reads. Declared structurally so this module (and
+ * therefore `@dereekb/firebase-server` core) takes no dependency on Express' types, letting both the
+ * HTTP controller and an MCP tool handler pass whatever request object they hold.
+ */
+export interface ClientIpRequest {
+    readonly headers?: Maybe<Record<string, Maybe<string | string[]>>>;
+    readonly ip?: Maybe<string>;
+    readonly socket?: Maybe<{
+        readonly remoteAddress?: Maybe<string>;
+    }>;
+}
+/**
+ * Resolves the calling client's IP address from a request, preferring the leftmost
+ * {@link FORWARDED_FOR_REQUEST_HEADER} entry and falling back to Express' own `req.ip` and then the
+ * raw socket address.
+ *
+ * IPv4-mapped IPv6 addresses (`::ffff:127.0.0.1`) are normalized to their dotted-quad form, so the
+ * same caller reaching a dual-stack listener and a v4-only one compares equal.
+ *
+ * **This is an advisory address, not an authentication factor.** Behind a proxy that does not
+ * rewrite the header it is caller-controlled, and a NAT/mobile caller's address changes on its own.
+ * Use it for binding a capability to the network path that minted it (an opt-in defence in depth
+ * alongside a real gate) or for logging — never as the sole check.
+ *
+ * @param request - The incoming request.
+ * @returns The resolved client address, or `undefined` when none could be determined.
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function requestClientIp(request: Maybe<ClientIpRequest>): Maybe<string>;
+/**
+ * Trims an address and unwraps the IPv4-mapped IPv6 form, returning `undefined` for an empty value.
+ *
+ * @param value - The raw address.
+ * @returns The normalized address, or `undefined` when there is nothing usable.
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function normalizeClientIp(value: Maybe<string>): Maybe<string>;
+/**
+ * Compares two client addresses for the purposes of a mint/redeem binding.
+ *
+ * Both sides are normalized first, and an ABSENT address on either side is treated as a MISMATCH:
+ * a binding that silently passes when the address could not be resolved would be no binding at all.
+ *
+ * @param a - The first address.
+ * @param b - The second address.
+ * @returns True when both addresses resolved and are equal.
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function clientIpsMatch(a: Maybe<string>, b: Maybe<string>): boolean;

package/test/index.esm.js

@@ -5089,6 +5089,7 @@ function _unsupported_iterable_to_array(o, minLen) {
                             callbackUrl: callbackUrl,
                             accessToken: tokenBody === null || tokenBody === void 0 ? void 0 : tokenBody.access_token,
                             idToken: tokenBody === null || tokenBody === void 0 ? void 0 : tokenBody.id_token,
+                            refreshToken: tokenBody === null || tokenBody === void 0 ? void 0 : tokenBody.refresh_token,
                             tokenType: tokenBody === null || tokenBody === void 0 ? void 0 : tokenBody.token_type,
                             scope: tokenBody === null || tokenBody === void 0 ? void 0 : tokenBody.scope,
                             session: {

package/test/package.json

@@ -1,19 +1,19 @@
 {
   "name": "@dereekb/firebase-server/test",
-  "version": "14.4.0",
+  "version": "14.5.1",
   "sideEffects": false,
   "type": "module",
   "peerDependencies": {
-    "@dereekb/analytics": "14.4.0",
-    "@dereekb/date": "14.4.0",
-    "@dereekb/firebase": "14.4.0",
-    "@dereekb/firebase-server": "14.4.0",
-    "@dereekb/firebase-server/oidc": "14.4.0",
-    "@dereekb/model": "14.4.0",
-    "@dereekb/nestjs": "14.4.0",
-    "@dereekb/oauth-resource": "14.4.0",
-    "@dereekb/rxjs": "14.4.0",
-    "@dereekb/util": "14.4.0",
+    "@dereekb/analytics": "14.5.1",
+    "@dereekb/date": "14.5.1",
+    "@dereekb/firebase": "14.5.1",
+    "@dereekb/firebase-server": "14.5.1",
+    "@dereekb/firebase-server/oidc": "14.5.1",
+    "@dereekb/model": "14.5.1",
+    "@dereekb/nestjs": "14.5.1",
+    "@dereekb/oauth-resource": "14.5.1",
+    "@dereekb/rxjs": "14.5.1",
+    "@dereekb/util": "14.5.1",
     "@google-cloud/firestore": "^7.11.6",
     "@google-cloud/storage": "^7.22.0",
     "@nestjs/common": "^12.0.1",
@@ -26,7 +26,7 @@
     "supertest": "^7.2.2"
   },
   "devDependencies": {
-    "@dereekb/nestjs": "14.4.0"
+    "@dereekb/nestjs": "14.5.1"
   },
   "exports": {
     "./package.json": "./package.json",