94 lines
3.2 KiB
Markdown
94 lines
3.2 KiB
Markdown
# 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.
|