# macos-keychain.schemas

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->
## 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

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

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

## Usage: Advanced Example

```ts
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.