@keyring/core

npm install @keyring/core

export function bunyanRedactSerializers(options?: RedactOptions): Record<string, (input: unknown) => unknown>;

export function bunyanRedactStream(target: WritableLike, options?: RedactOptions): NodeJS.WritableStream;

export function constantTimeEqual(a: Uint8Array, b: Uint8Array): boolean;

export function crc32(input: string | Uint8Array): number;

export function crc32Hex(input: string | Uint8Array): string;

export function displayPrefixOf(raw: string): string;

export function encodeHashKey(hash: Uint8Array): string;

export function formatKey(input: FormatKeyInput): string;

export function generateKey(input: {
    kind?: KeyKind;
    env: Environment;
}): string;

export function hasAllScopes(granted: readonly string[], required: readonly string[]): boolean;

export function hasScope(granted: readonly string[], required: string): boolean;

export function isAuthoritativeMiss(status: PolicyStoreStatus, options: FreshnessOptions = {}): boolean;

export function isRateLimitRule(value: unknown): value is RateLimitRule;

export function isRateLimitRuleSet(value: unknown): value is readonly RateLimitRule[];

export function looksLikeKeyringKey(raw: string): boolean;

export function lookupHash(rawKey: string): Buffer;

export function lookupHashKey(rawKey: string): string;

export function mintKey(input: {
    kind?: KeyKind;
    env: Environment;
}): MintedKey;

export function missingScopes(granted: readonly string[], required: readonly string[]): string[];

export function parseKey(raw: string): ParsedKey;

export function pinoRedact(options?: RedactOptions): PinoRedactHooks;

export function prefixFor(kind: KeyKind, env: Environment): string;

export function rateLimitHeaders(states: readonly RateLimitState[], options: RateLimitHeaderOptions = {}): Record<string, string>;

export function rateLimitSubject(rule: RateLimitRule, key: {
    keyId: string | null;
    tenantId: string | null;
}): string | null;

export function redact(value: unknown, options: RedactOptions = {}): unknown;

export function redactString(value: string, replacement: string = DEFAULT_REPLACEMENT): string;

export function scopeMatches(granted: string, required: string): boolean;

export function secret<T>(value: T): Secret<T>;

export function stalenessMs(status: PolicyStoreStatus, now: number = Date.now()): number | null;

export function toRateLimitRule(wire: WireRateLimit): RateLimitRule;

export function toWireRateLimit(rule: RateLimitRule): WireRateLimit;

export function tryParseKey(raw: string): ParseResult;

export function verify(rawKey: string, options: VerifyOptions): VerifyResult;

export function winstonRedact(options?: RedactOptions): WinstonTransformFunction;

export class KeyringError extends Error {
    readonly code: KeyringErrorCode;
    constructor(code: KeyringErrorCode, message: string);
}

export class MemoryPolicyStore implements PolicyStore {
    constructor(policies: Iterable<KeyPolicy> = []);
    get(lookupHashKey: string): KeyPolicy | undefined;
    status(): PolicyStoreStatus;
    markLoaded(status: PolicyStoreStatus): void;
    set(policy: KeyPolicy): void;
    delete(policy: Pick<KeyPolicy, 'lookupHash'>): boolean;
    clear(): void;
    get size(): number;
}

export class Secret<T> {
    constructor(value: T);
    expose(): T;
    toString(): string;
    toJSON(): string;
    [Symbol.for('nodejs.util.inspect.custom')](): string;
}

export interface FormatKeyInput {
  readonly kind?: KeyKind;
  readonly env: Environment;
  /** Exactly {@link SECRET_BYTES} bytes of CSPRNG output. */
  readonly secret: Uint8Array;
}

export interface FreshnessOptions {
  /** Epoch ms. */
  readonly now?: number;
  /** Report section 2.6's belt and braces: 60 s by default. */
  readonly maxStalenessMs?: number;
}

export interface KeyPolicy {
  readonly keyId: string;
  readonly workspaceId: string;
  readonly projectId: string;
  readonly tenantId: string;
  readonly env: Environment;
  /** SHA-256 of the raw key, 32 bytes. */
  readonly lookupHash: Uint8Array;
  readonly displayPrefix: string;
  readonly scopes: readonly string[];
  /** Epoch milliseconds, or null for "never expires". */
  readonly expiresAt: number | null;
  /** Epoch milliseconds, or null for "not revoked". */
  readonly revokedAt: number | null;
  /**
   * The limits that apply to this key, already resolved by the control plane
   * against the project default (migration 0008) so the layering happens in one
   * place rather than in three SDKs. An empty array is "no limits", which is
   * the common case and the reason a rate-limited product can still answer most
   * requests without a network call.
   */
  readonly rateLimits: readonly RateLimitRule[];
}

export interface MintedKey {
  /** The plaintext. It exists in exactly one response body and is never stored. */
  readonly plaintext: Secret<string>;
  readonly kind: KeyKind;
  readonly env: Environment;
  /** Safe to store and to show in a dashboard. */
  readonly displayPrefix: string;
  /** SHA-256 of the plaintext; the cache index and the snapshot value. */
  readonly lookupHash: Buffer;
}

export interface ParsedKey {
  readonly kind: KeyKind;
  readonly env: Environment;
  /** e.g. `kr_live_` — includes the trailing underscore. */
  readonly prefix: string;
  /** 32 base64url characters. */
  readonly body: string;
  /** 8 lowercase hex characters. */
  readonly checksum: string;
  /** e.g. `kr_live_a1b2c3` — safe to log, safe to store, useless as a credential. */
  readonly displayPrefix: string;
}

export interface PinoRedactHooks {
  readonly logMethod: LogMethodHook;
  readonly streamWrite: (s: string) => string;
}

export interface PolicyStore {
  get(lookupHashKey: string): KeyPolicy | undefined;
  status(): PolicyStoreStatus;
}

export interface PolicyStoreStatus {
  /** The snapshot version these contents came from; null if none ever loaded. */
  readonly snapshotVersion: number | null;
  /** Epoch ms of the last successful load or refresh; null if none. */
  readonly fetchedAt: number | null;
  readonly source: PolicyStoreSource;
  /**
   * True when the store holds *every* key in its scope at `snapshotVersion`.
   *
   * This is the load-bearing field, and the reason section 6.4 can defend
   * `stale-then-open` as a default: the argument is "the cache is complete for
   * the project, so a key that is not in it does not exist". A store that has
   * evicted under `maxCachedKeys`, or that was filled from a tenant-filtered
   * snapshot, is not complete, and a miss from it proves nothing.
   */
  readonly complete: boolean;
}

export interface RateLimitHeaderOptions {
  /** Report section 3.6: on by default. */
  readonly legacy?: boolean;
  /** The policy that refused, when one did. */
  readonly limitedId?: string | null;
  readonly retryAfterSeconds?: number | null;
}

export interface RateLimitRule {
  /**
   * The name the caller sees in `RateLimit-Policy` and in
   * `Keyring-Rate-Limited-Policy`. Report section 3.6 follows Stripe in naming
   * which limiter fired; it costs nothing and saves a support ticket.
   */
  readonly id: string;
  /** Requests permitted per window. */
  readonly limit: number;
  readonly windowMs: number;
  readonly algorithm: 'sliding' | 'fixed';
  readonly scope: 'key' | 'tenant';
}

export interface RateLimitState {
  readonly id: string;
  readonly limit: number;
  readonly windowMs: number;
  readonly scope: 'key' | 'tenant';
  /** Requests left in the window. Never negative. */
  readonly remaining: number;
  /** Milliseconds until the window that bounds `remaining` resets. */
  readonly resetMs: number;
}

export interface RateLimitTarget {
  readonly projectId: string;
  readonly env: Environment;
  readonly keyId: string | null;
  readonly tenantId: string | null;
}

export interface RedactOptions {
  readonly replacement?: string;
  readonly maxDepth?: number;
}

export interface VerifiedKey {
  readonly keyId: string;
  readonly workspaceId: string;
  readonly projectId: string;
  readonly tenantId: string;
  readonly env: Environment;
  readonly scopes: readonly string[];
  readonly displayPrefix: string;
  readonly expiresAt: number | null;
  readonly rateLimits: readonly RateLimitRule[];
}

export interface VerifyFailure {
  readonly ok: false;
  /** Safe to return to the caller. */
  readonly code: PublicErrorCode;
  /** Safe to return to the caller. */
  readonly status: 401 | 403;
  /** Safe to return to the caller. Never names the actual cause of a 401. */
  readonly message: string;
  /** For the vendor's request log only. Never serialise this to the caller. */
  readonly reason: DenialReason;
  /** Present when the key parsed; useful for the request log. */
  readonly displayPrefix?: string;
  /** Scopes the key was missing, when `reason` is `insufficient_scope`. */
  readonly missingScopes?: readonly string[];
}

export interface VerifyOptions {
  /** The local policy cache. Never a network client. */
  readonly store: PolicyStore;
  /**
   * The environment this call site serves. When set, a key minted for the other
   * environment is rejected even if it is otherwise valid — the second of the
   * three enforcement layers in report section 5.2.
   */
  readonly env?: Environment;
  readonly requiredScopes?: readonly string[];
  /** Epoch milliseconds. Injectable so expiry is testable and fixture-driven. */
  readonly now?: number;
}

export interface VerifySuccess {
  readonly ok: true;
  readonly key: VerifiedKey;
}

export interface WireRateLimit {
  readonly id: string;
  readonly limit: number;
  readonly window_ms: number;
  readonly algorithm: 'sliding' | 'fixed';
  readonly scope: 'key' | 'tenant';
}

export type DenialReason =
  | 'malformed'
  | 'bad_checksum'
  | 'unknown_key'
  | 'hash_mismatch'
  | 'env_mismatch'
  | 'revoked'
  | 'expired'
  | 'insufficient_scope';

export type Environment = 'live' | 'test';

export type KeyKind = 'api' | 'secret';

export type KeyringErrorCode =
  'invalid_configuration' | 'invalid_key_format' | 'unsupported_pepper_version';

export type ParseResult =
  | { readonly ok: true; readonly key: ParsedKey }
  | {
      readonly ok: false;
      readonly reason: Extract<DenialReason, 'malformed' | 'bad_checksum'>;
    };

export type PolicyStoreSource = 'none' | 'disk' | 'network';

export type PublicErrorCode = 'invalid_key' | 'insufficient_scope';

export type VerifyResult = VerifySuccess | VerifyFailure;

const BODY_LENGTH: 32;

const CHECKSUM_LENGTH: 8;

const DEFAULT_MAX_STALENESS_MS: 60000;

const DEFAULT_REPLACEMENT: "[redacted]";

const DISPLAY_BODY_CHARS: 6;

const ENVIRONMENTS: readonly Environment[];

const KIND_PREFIX: Record<KeyKind, string>;

const LOOKUP_HASH_BYTES: 32;

const MAX_RATE_LIMIT: 1000000000;

const MAX_RATE_LIMIT_WINDOW_MS: 2678400000;

const MAX_RATE_LIMITS_PER_KEY: 8;

const MIN_RATE_LIMIT_WINDOW_MS: 1000;

const NO_SNAPSHOT: PolicyStoreStatus;

const PUBLIC_MESSAGES: Record<PublicErrorCode, string>;

const SECRET_BYTES: 24;