macos-keychain.schemas

(no submodules)

Purpose

Provides runtime Zod schemas that mirror the public type contracts. They are parsed at every consumer boundary so an invalid timeoutMs, missing required field, or wrong-shape logger surfaces as a precise ZodError rather than a downstream undefined-behaviour failure deep inside the bridge.

The schemas are colocated with the rest of the package surface but are also exposed via the dedicated ./schemas/macos-keychain.schemas subpath so a calling library can re-validate config it received from elsewhere (CLI flags, config file, environment) before constructing the bridge.

Features

KeychainConfigSchema — structural shape of bridge construction options.
KeychainItemSchema — full credential record (used by the parser).
KeychainResultSchema — boolean success envelope.
Inferred types — KeychainConfigInput, KeychainItemInput, KeychainResultInput — parallel the canonical interfaces with the parsing defaults applied.

Usage: Basic Example

import { KeychainConfigSchema } from "@suaveplan/macos-keychain";

const config = KeychainConfigSchema.parse({
    serviceName: "my-app",
    timeoutMs: 5_000,
});

Usage: Advanced Example

import {
    KeychainConfigSchema,
    KeychainItemSchema,
} from "@suaveplan/macos-keychain";

function loadKeychainConfigFromCli(rawArgs: Record<string, unknown>) {
    const result = KeychainConfigSchema.safeParse({
        serviceName: rawArgs["service"],
        timeoutMs: Number(rawArgs["timeout"]) || undefined,
    });
    if (!result.success) {
        throw new Error(
            `Invalid keychain CLI flags: ${result.error.message}`
        );
    }
    return result.data;
}

const stored = KeychainItemSchema.parse({
    service: "github",
    account: "alice",
    password: "ghp_…",
});
void stored;
void loadKeychainConfigFromCli;

API Reference

KeychainConfigSchema — Zod object schema. Every field optional; timeoutMs validated as a positive integer; clock validated as a function; logger validated as an object exposing the four LoggerLike methods.
KeychainItemSchema — Zod object schema requiring non-empty service and account strings, capping password at 1 MiB, and accepting optional label, comment, createdAt, modifiedAt.
KeychainResultSchema — Zod object schema with required success boolean and optional error string.
Inferred types — re-exported via z.infer<typeof Schema> for callers that want a single source of truth for both runtime and compile-time validation.

Implementation Notes

Schemas use z.custom for clock and logger because they are structural function/object shapes. Zod's .parse would otherwise narrow them to unknown without a type assertion.
The password upper bound exists because the macOS security CLI enforces a similar limit and a multi-megabyte payload almost certainly indicates a programming error or accidental binary blob.
Schemas do not validate the platform itself — the bridge throws KEYCHAIN.UNAVAILABLE at runtime when invoked off macOS, but constructing the schema and parsing inputs remains valid on any platform.

3.2 KiB Raw Blame History