@venn-lang/auth 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vinicius Borges
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,140 @@
+# @venn-lang/auth
+
+> The `auth` namespace: build the header a request needs, or fetch a token for it.
+
+Six of the seven verbs are pure computation, headers, signatures and codes worked out from what you
+hand them. The seventh, `auth.oauth2`, is the one that talks to a token endpoint, and it goes
+through the `AuthClient` port so the exchange is injected rather than hard-wired. Real cryptography
+uses the global Web Crypto (`crypto.subtle`), so nothing here imports `node:*`.
+
+## Install
+
+Nothing to install. `@venn-lang/auth` is part of the standard library, and the CLI and the language
+server both load [`@venn-lang/stdlib`](../stdlib), which lists every stdlib plugin. A file reaches the
+namespace with one line.
+
+```ruby
+use "venn/auth"
+```
+
+## Usage
+
+```ruby
+module demo.auth
+
+use "venn/auth"
+use "venn/assert"
+
+flow "Signed in" {
+  step "a bearer header carries the token" {
+    const header = auth.bearer "tok123"
+    expect header.Authorization == "Bearer tok123"
+  }
+
+  step "a service account gets a token" {
+    const token = auth.oauth2 "svc-account" { grant: "client_credentials", scope: "orders:write" }
+    expect token.expires_in > 0
+  }
+}
+```
+
+## Verbs
+
+| Verb | Call | Result |
+| --- | --- | --- |
+| `auth.bearer` | `auth.bearer "tok123"` | `auth.Headers` |
+| `auth.basic` | `auth.basic "alice" "s3cret"` | `auth.Headers` |
+| `auth.apikey` | `auth.apikey "KEY" { header: "X-Token" }` | `auth.Headers` |
+| `auth.hmac` | `auth.hmac "s3cret" "payload" { algo: "sha512" }` | `string`, lowercase hex |
+| `auth.totp` | `auth.totp "seed" { at: 0, period: 30, digits: 6 }` | `string` |
+| `auth.jwt` | `auth.jwt { payload: { sub: "42" }, secret: "k" }` | `string` |
+| `auth.oauth2` | `auth.oauth2 "svc-account" { grant: "client_credentials" }` | `auth.Token` |
+
+**`bearer`** returns `{ Authorization: "Bearer <token>" }`.
+
+**`basic`** base64-encodes `user:pass` into `{ Authorization: "Basic <…>" }`.
+
+**`apikey`** puts the key under a header of your choosing. The `header` option defaults to
+`X-API-Key`, so `auth.apikey "KEY"` gives `{ "X-API-Key": "KEY" }`.
+
+**`hmac`** takes the secret first and the payload second, so `auth.hmac "s3cret" "payload"` keys the
+HMAC with `s3cret`. The `algo` option accepts `sha1`, `sha256`, `sha384` and `sha512`, case and
+dashes ignored, and anything it does not recognise falls back to SHA-256.
+
+**`totp`** computes an RFC 6238 code and is deterministic for a fixed `at`, which makes it usable in
+a test. `at` is the time to compute at and `period` the step, both in seconds; `digits` defaults
+to 6 and the result is zero-padded, which is why it is a string and not a number.
+
+**`jwt`** takes nothing positionally. `payload` and `secret` are required options, `header` is
+optional and is merged over the default `{ alg: "HS256", typ: "JWT" }`. The signature is HS256.
+
+**`oauth2`** takes the principal positionally and `grant`, `tokenUrl`, `scope` and `refresh` as
+options. It is the only verb here that reaches a port.
+
+## The types it publishes
+
+| Type | Shape |
+| --- | --- |
+| `auth.Headers` | `map<string>`. A map rather than a record, because `auth.apikey` names its own header and the key is only known at the call site. |
+| `auth.Token` | `{ access_token, token_type, expires_in }`, the OAuth2 wire shape. |
+
+## The AuthClient port
+
+| | |
+| --- | --- |
+| id | `venn.port.auth-client` |
+| version | 1 |
+| requires | `net` |
+| methods | `token` |
+
+Two implementations ship together, which is what makes this a port rather than a module with a good
+interface:
+
+- `createFakeAuthClient()` returns a canned token derived from the principal, with no network. This
+  is the one [`@venn-lang/stdlib`](../stdlib) binds, so `auth.oauth2` resolves offline. Pass
+  `{ token: { expires_in: 60 } }` to override any field of what it hands back.
+- `createRealAuthClient()` is a stub. Every call throws a `VennError` with code `VN8090`, because
+  this repository is the language and ships no live token exchange.
+
+Both run the same conformance suite, `authClientConformance` in `src/clients/auth-client.suite.ts`:
+a `token` resolves with a string `access_token`, a string `token_type` and a numeric `expires_in`.
+
+The plugin as a whole declares `requires: ["net"]`, so a host without the `net` capability is
+refused with a legible diagnostic before the run starts, rather than failing somewhere inside
+`auth.oauth2`.
+
+## API
+
+| Export | What it is |
+| --- | --- |
+| `authPlugin` | The plugin definition: namespace `auth`, `requires: ["net"]`. Also the default export. |
+| `authActions` | The seven action definitions: `bearer`, `basic`, `apikey`, `hmac`, `totp`, `jwt`, `oauth2`. |
+| `AuthClientPort` | The port descriptor. |
+| `AuthClient` | The port interface: `token(request)`. |
+| `OAuthTokenRequest` | What the port is asked: `principal`, and the optional `grant`, `tokenUrl`, `scope`, `refresh`. |
+| `OAuthToken` | What it answers: `{ access_token, token_type, expires_in }`. |
+| `createFakeAuthClient({ token? })` | The deterministic double. |
+| `createRealAuthClient()` | The real client, stubbed to throw `VN8090`. |
+| `Token` | The Zod schema registered as the plugin's nominal `Token` type. |
+| `authTypeDefs` | The `TypeSpec`s for `auth.Headers` and `auth.Token`, which the checker and the LSP read. |
+
+Binding a different client means one entry in the runner's port list:
+
+```ts
+import { AuthClientPort, createFakeAuthClient } from "@venn-lang/auth";
+import { createRunner } from "@venn-lang/runtime";
+
+const runner = createRunner({
+  host,
+  plugins,
+  sink,
+  uri,
+  ports: [{ port: AuthClientPort, impl: createFakeAuthClient() }],
+});
+```
+
+## See also
+
+- [`@venn-lang/http`](../std-http) for the requests these headers are attached to.
+- [`@venn-lang/crypto`](../std-crypto) for hashing and encoding outside an auth flow.
+- [`@venn-lang/sdk`](../sdk) for `definePlugin` and `defineAction`.

package/dist/index.d.ts

@@ -0,0 +1,86 @@
+import { ActionDefinition, PluginDefinition, ZodType } from "@venn-lang/sdk";
+import { TypeSpec } from "@venn-lang/types";
+import { Port } from "@venn-lang/contracts";
+//#region src/actions/index.d.ts
+/** The auth namespace's verbs. Adding one is a single line here. */
+declare const authActions: ActionDefinition[];
+//#endregion
+//#region src/port/auth-client.types.d.ts
+/** Arguments for {@link AuthClient.token}: which principal, and how to obtain or refresh it. */
+interface OAuthTokenRequest {
+  principal: string;
+  grant?: string;
+  tokenUrl?: string;
+  scope?: string;
+  refresh?: string;
+}
+/** A token as the endpoint answered with it. Snake case, because that is the wire shape. */
+interface OAuthToken {
+  access_token: string;
+  token_type: string;
+  expires_in: number;
+}
+/**
+ * The contract `auth.oauth2` acquires tokens through.
+ *
+ * Reached via `ctx.port(AuthClientPort)`, never by calling an endpoint directly.
+ */
+interface AuthClient {
+  token(request: OAuthTokenRequest): Promise<OAuthToken>;
+}
+//#endregion
+//#region src/port/auth-client.port.d.ts
+/**
+ * The port `auth.oauth2` obtains its tokens through.
+ *
+ * Bound by the host to `createFakeAuthClient` or `createRealAuthClient`.
+ * Requires the `net` capability, so a host without it is refused at load time
+ * rather than failing mid-run.
+ */
+declare const AuthClientPort: Port<AuthClient>;
+//#endregion
+//#region src/clients/fake-client.d.ts
+/**
+ * The in-process `AuthClient`: a canned token derived from the principal, no network.
+ *
+ * @param args.token Fields to override on every token it hands back.
+ */
+declare function createFakeAuthClient(args?: {
+  token?: Partial<OAuthToken>;
+}): AuthClient;
+//#endregion
+//#region src/clients/real-client.d.ts
+/**
+ * The endpoint-backed `AuthClient`. Not implemented in this build.
+ *
+ * @throws VennError `VN8090` on every call, so a host that binds it fails loudly
+ * instead of quietly handing a script a token that was never obtained.
+ */
+declare function createRealAuthClient(): AuthClient;
+//#endregion
+//#region src/plugin.d.ts
+/**
+ * The `auth` plugin: header builders, signing helpers and an OAuth2 exchange.
+ *
+ * Every verb but `auth.oauth2` is pure. That one reaches out through
+ * `AuthClientPort`, which is why the whole plugin declares the `net` capability
+ * and is refused at load time on a host that cannot offer it.
+ */
+declare const authPlugin: PluginDefinition;
+//#endregion
+//#region src/types/token.d.ts
+/** Runtime schema for the nominal `Token` type, the value `auth.oauth2` yields. */
+declare const Token: ZodType;
+//#endregion
+//#region src/types/type-defs.d.ts
+/**
+ * The named types `@venn-lang/auth` publishes to scripts, keyed by their bare name.
+ *
+ * `Token` restates `OAuthToken` in `port/auth-client.types.ts` and, field for
+ * field, the Zod `Token` next door. Each serves a different reader: Zod checks a
+ * value that arrived, this types a call being written. Change all three together.
+ */
+declare const authTypeDefs: Readonly<Record<string, TypeSpec>>;
+//#endregion
+export { type AuthClient, AuthClientPort, type OAuthToken, type OAuthTokenRequest, Token, authActions, authPlugin, authPlugin as default, authTypeDefs, createFakeAuthClient, createRealAuthClient };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/actions/index.ts","../src/port/auth-client.types.ts","../src/port/auth-client.port.ts","../src/clients/fake-client.ts","../src/clients/real-client.ts","../src/plugin.ts","../src/types/token.ts","../src/types/type-defs.ts"],"mappings":";;;;;cAUa,aAAa;;;;UCTT;EACf;EACA;EACA;EACA;EACA;;;UAIe;EACf;EACA;EACA;;;;;;;UAQe;EACf,MAAM,SAAS,oBAAoB,QAAQ;;;;;;;;;;;cCZhC,gBAAgB,KAAK;;;;;;;;iBCHlB,qBAAqB;EAAQ,QAAQ,QAAQ;IAAqB;;;;;;;;;iBCElE,wBAAwB;;;;;;;;;;cCE3B,YAAY;;;;cCRZ,OAAO;;;;;;;;;;cCMP,cAAc,SAAS,eAAe"}

package/dist/index.js

@@ -0,0 +1,343 @@
+import { arg, defineAction, definePlugin, z } from "@venn-lang/sdk";
+import { t } from "@venn-lang/types";
+import { VennError } from "@venn-lang/contracts";
+/**
+* `auth.apikey(key, { header })`: a one-entry header object carrying an API key.
+*
+* The header name defaults to `X-API-Key`. Pure, no network.
+*/
+const apikey = defineAction({
+	name: "apikey",
+	doc: "Build a header object carrying an API key.",
+	params: z.object({ header: z.string().optional() }).optional(),
+	args: [arg("key", t.string, "The API key itself.")],
+	result: t.ref("auth.Headers"),
+	run: (_ctx, input) => {
+		return { [input.params?.header ?? "X-API-Key"]: String(input.args[0] ?? "") };
+	}
+});
+//#endregion
+//#region src/actions/basic.ts
+/**
+* `auth.basic(username, password)`: an `Authorization: Basic …` header.
+*
+* The credentials are base64 of `user:pass`, which is encoding and not secrecy.
+* A password read from `secrets.*` stays redacted in every diagnostic.
+*/
+const basic = defineAction({
+	name: "basic",
+	doc: "Build a Basic Authorization header from a username and password.",
+	args: [arg("username", t.string, "Who is signing in."), arg("password", t.string, "Their password. A secret stays redacted.")],
+	result: t.ref("auth.Headers"),
+	run: (_ctx, input) => basicHeader(String(input.args[0] ?? ""), String(input.args[1] ?? ""))
+});
+function basicHeader(user, pass) {
+	return { Authorization: `Basic ${btoa(`${user}:${pass}`)}` };
+}
+//#endregion
+//#region src/actions/bearer.ts
+/** `auth.bearer(token)`: an `Authorization: Bearer …` header. Pure, no network. */
+const bearer = defineAction({
+	name: "bearer",
+	doc: "Build an Authorization header for a bearer token.",
+	args: [arg("token", t.string, "The token to carry.")],
+	result: t.ref("auth.Headers"),
+	run: (_ctx, input) => ({ Authorization: `Bearer ${String(input.args[0] ?? "")}` })
+});
+//#endregion
+//#region src/crypto/bytes.ts
+/** UTF-8 encode a string. The copy is ArrayBuffer-backed, the only shape WebCrypto accepts. */
+function encodeUtf8(text) {
+	return Uint8Array.from(new TextEncoder().encode(text));
+}
+/** Lowercase hex of a byte array. */
+function toHex(bytes) {
+	let out = "";
+	for (const byte of bytes) out += byte.toString(16).padStart(2, "0");
+	return out;
+}
+/** URL-safe, unpadded base64 (base64url) of a byte array. */
+function toBase64Url(bytes) {
+	let binary = "";
+	for (const byte of bytes) binary += String.fromCharCode(byte);
+	return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+//#endregion
+//#region src/crypto/hmac.ts
+const ALGOS = {
+	sha1: "SHA-1",
+	sha256: "SHA-256",
+	sha384: "SHA-384",
+	sha512: "SHA-512"
+};
+/**
+* Map whatever the script wrote (`sha256`, `SHA-256`) to a WebCrypto hash name.
+*
+* An unknown label falls back to SHA-256 rather than throwing.
+*/
+function normalizeHash(algo) {
+	const key = (algo ?? "sha256").toLowerCase().replace(/-/g, "");
+	return ALGOS[key] ?? "SHA-256";
+}
+/** Raw HMAC bytes over `message`, keyed by `secret`, using the global Web Crypto. */
+async function hmacRaw(args) {
+	const key = await crypto.subtle.importKey("raw", encodeUtf8(args.secret), {
+		name: "HMAC",
+		hash: normalizeHash(args.algo)
+	}, false, ["sign"]);
+	const signature = await crypto.subtle.sign("HMAC", key, args.message);
+	return new Uint8Array(signature);
+}
+/** Lowercase hex HMAC over a string `payload`, keyed by `secret` (default SHA-256). */
+async function hmacHex(args) {
+	return toHex(await hmacRaw({
+		secret: args.secret,
+		message: encodeUtf8(args.payload),
+		algo: args.algo
+	}));
+}
+//#endregion
+//#region src/crypto/jwt.ts
+/**
+* Sign a compact HS256 JWT.
+*
+* @param args.header Merged over `{ alg: "HS256", typ: "JWT" }`, so a caller can
+* add claims like `kid` but overriding `alg` does not change how it is signed.
+*/
+async function signJwt(args) {
+	const signingInput = `${encodeSegment({
+		alg: "HS256",
+		typ: "JWT",
+		...args.header ?? {}
+	})}.${encodeSegment(args.payload)}`;
+	return `${signingInput}.${toBase64Url(await hmacRaw({
+		secret: args.secret,
+		message: encodeUtf8(signingInput),
+		algo: "sha256"
+	}))}`;
+}
+function encodeSegment(value) {
+	return toBase64Url(encodeUtf8(JSON.stringify(value)));
+}
+//#endregion
+//#region src/crypto/totp.ts
+/**
+* An RFC 6238 TOTP code: SHA-1, a 30 second period and 6 digits by default.
+*
+* @param args.at The instant to compute for, in seconds. Fixing it fixes the code.
+*/
+async function totpCode(args) {
+	const period = args.period ?? 30;
+	const digits = args.digits ?? 6;
+	const counter = Math.floor((args.at ?? 0) / period);
+	return truncate({
+		mac: await hmacRaw({
+			secret: args.seed,
+			message: counterBytes(counter),
+			algo: "sha1"
+		}),
+		digits
+	});
+}
+/** 8-byte big-endian counter, per HOTP (RFC 4226). */
+function counterBytes(counter) {
+	const buffer = /* @__PURE__ */ new Uint8Array(8);
+	let remaining = counter;
+	for (let i = 7; i >= 0; i -= 1) {
+		buffer[i] = remaining & 255;
+		remaining = Math.floor(remaining / 256);
+	}
+	return buffer;
+}
+/** Dynamic truncation of an HMAC into a zero-padded decimal code (RFC 4226 §5.3). */
+function truncate(args) {
+	const mac = args.mac;
+	const offset = byteAt(mac, mac.length - 1) & 15;
+	const binary = (byteAt(mac, offset) & 127) << 24 | byteAt(mac, offset + 1) << 16 | byteAt(mac, offset + 2) << 8 | byteAt(mac, offset + 3);
+	return String(binary % 10 ** args.digits).padStart(args.digits, "0");
+}
+function byteAt(bytes, index) {
+	return bytes[index] ?? 0;
+}
+/** `auth.hmac(secret, payload, { algo })`: a lowercase hex HMAC. Defaults to SHA-256. */
+const hmac = defineAction({
+	name: "hmac",
+	doc: "Compute a hex HMAC over a payload using a secret.",
+	params: z.object({ algo: z.string().optional() }).optional(),
+	args: [arg("payload", t.string, "What to sign."), arg("secret", t.string, "The shared secret.")],
+	result: t.string,
+	run: (_ctx, input) => hmacHex({
+		secret: String(input.args[0] ?? ""),
+		payload: String(input.args[1] ?? ""),
+		algo: input.params?.algo
+	})
+});
+/** `auth.jwt({ header, payload, secret })`: a compact HS256-signed JWT. */
+const jwt = defineAction({
+	name: "jwt",
+	doc: "Sign an HS256 JWT.",
+	params: z.object({
+		header: z.record(z.string(), z.unknown()).optional(),
+		payload: z.unknown(),
+		secret: z.string()
+	}),
+	result: t.string,
+	run: (_ctx, input) => signJwt({
+		header: input.params.header,
+		payload: input.params.payload,
+		secret: input.params.secret
+	})
+});
+//#endregion
+//#region src/port/auth-client.port.ts
+/**
+* The port `auth.oauth2` obtains its tokens through.
+*
+* Bound by the host to `createFakeAuthClient` or `createRealAuthClient`.
+* Requires the `net` capability, so a host without it is refused at load time
+* rather than failing mid-run.
+*/
+const AuthClientPort = {
+	id: "venn.port.auth-client",
+	version: 1,
+	requires: ["net"],
+	methods: ["token"]
+};
+/**
+* `auth.oauth2(principal, { grant, tokenUrl, scope, refresh })`: an `auth.Token`.
+*
+* The only verb here that leaves the process, and it does so through
+* `AuthClientPort` rather than calling the endpoint itself.
+*/
+const oauth2 = defineAction({
+	name: "oauth2",
+	doc: "Obtain an OAuth2 token for a principal via the AuthClient port.",
+	params: z.object({
+		grant: z.string().optional(),
+		tokenUrl: z.string().optional(),
+		scope: z.string().optional(),
+		refresh: z.string().optional()
+	}).optional(),
+	args: [arg("principal", t.string, "Who the token is for.")],
+	result: t.ref("auth.Token"),
+	run: (ctx, input) => ctx.port(AuthClientPort).token({
+		principal: String(input.args[0] ?? ""),
+		grant: input.params?.grant,
+		tokenUrl: input.params?.tokenUrl,
+		scope: input.params?.scope,
+		refresh: input.params?.refresh
+	})
+});
+//#endregion
+//#region src/actions/index.ts
+/** The auth namespace's verbs. Adding one is a single line here. */
+const authActions = [
+	bearer,
+	basic,
+	apikey,
+	hmac,
+	defineAction({
+		name: "totp",
+		doc: "Compute a TOTP code from a shared seed.",
+		params: z.object({
+			at: z.number().optional(),
+			period: z.number().optional(),
+			digits: z.number().optional()
+		}).optional(),
+		args: [arg("seed", t.string, "The shared seed, base32.")],
+		result: t.string,
+		run: (_ctx, input) => totpCode({
+			seed: String(input.args[0] ?? ""),
+			at: input.params?.at,
+			period: input.params?.period,
+			digits: input.params?.digits
+		})
+	}),
+	jwt,
+	oauth2
+];
+//#endregion
+//#region src/clients/fake-client.ts
+/**
+* The in-process `AuthClient`: a canned token derived from the principal, no network.
+*
+* @param args.token Fields to override on every token it hands back.
+*/
+function createFakeAuthClient(args = {}) {
+	return { token: async (request) => ({
+		access_token: `fake-access-token:${request.principal}`,
+		token_type: "Bearer",
+		expires_in: 3600,
+		...args.token
+	}) };
+}
+//#endregion
+//#region src/clients/real-client.ts
+/**
+* The endpoint-backed `AuthClient`. Not implemented in this build.
+*
+* @throws VennError `VN8090` on every call, so a host that binds it fails loudly
+* instead of quietly handing a script a token that was never obtained.
+*/
+function createRealAuthClient() {
+	return { token: async () => {
+		throw new VennError({
+			code: "VN8090",
+			message: "OAuth2 real client not implemented in this build"
+		});
+	} };
+}
+//#endregion
+//#region src/types/token.ts
+/** Runtime schema for the nominal `Token` type, the value `auth.oauth2` yields. */
+const Token = z.object({
+	access_token: z.string(),
+	token_type: z.string(),
+	expires_in: z.number()
+});
+//#endregion
+//#region src/types/type-defs.ts
+/**
+* The named types `@venn-lang/auth` publishes to scripts, keyed by their bare name.
+*
+* `Token` restates `OAuthToken` in `port/auth-client.types.ts` and, field for
+* field, the Zod `Token` next door. Each serves a different reader: Zod checks a
+* value that arrived, this types a call being written. Change all three together.
+*/
+const authTypeDefs = {
+	/**
+	* What the header builders hand back, ready to go into a request's `headers`.
+	*
+	* A map rather than a record: `auth.apikey` names its own header, so the key
+	* is only known at the call. The values are always strings.
+	*/
+	Headers: t.map(t.string),
+	/** An OAuth2 token, as the token endpoint answered with it. */
+	Token: t.record({
+		access_token: t.string,
+		token_type: t.string,
+		expires_in: t.number
+	})
+};
+//#endregion
+//#region src/plugin.ts
+/**
+* The `auth` plugin: header builders, signing helpers and an OAuth2 exchange.
+*
+* Every verb but `auth.oauth2` is pure. That one reaches out through
+* `AuthClientPort`, which is why the whole plugin declares the `net` capability
+* and is refused at load time on a host that cannot offer it.
+*/
+const authPlugin = definePlugin({
+	name: "venn/auth",
+	version: "0.0.0",
+	namespace: "auth",
+	requires: ["net"],
+	actions: authActions,
+	types: { Token },
+	typeDefs: authTypeDefs
+});
+//#endregion
+export { AuthClientPort, Token, authActions, authPlugin, authPlugin as default, authTypeDefs, createFakeAuthClient, createRealAuthClient };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["params","params","params","params"],"sources":["../src/actions/apikey.ts","../src/actions/basic.ts","../src/actions/bearer.ts","../src/crypto/bytes.ts","../src/crypto/hmac.ts","../src/crypto/jwt.ts","../src/crypto/totp.ts","../src/actions/hmac.ts","../src/actions/jwt.ts","../src/port/auth-client.port.ts","../src/actions/oauth2.ts","../src/actions/totp.ts","../src/actions/index.ts","../src/clients/fake-client.ts","../src/clients/real-client.ts","../src/types/token.ts","../src/types/type-defs.ts","../src/plugin.ts"],"sourcesContent":["import { type ActionDefinition, arg, defineAction, z } from \"@venn-lang/sdk\";\nimport { t } from \"@venn-lang/types\";\n\nconst params = z.object({ header: z.string().optional() }).optional();\n\n/**\n * `auth.apikey(key, { header })`: a one-entry header object carrying an API key.\n *\n * The header name defaults to `X-API-Key`. Pure, no network.\n */\nexport const apikey: ActionDefinition = defineAction({\n  name: \"apikey\",\n  doc: \"Build a header object carrying an API key.\",\n  params,\n  args: [arg(\"key\", t.string, \"The API key itself.\")],\n  result: t.ref(\"auth.Headers\"),\n  run: (_ctx, input) => {\n    const header = input.params?.header ?? \"X-API-Key\";\n    return { [header]: String(input.args[0] ?? \"\") };\n  },\n});\n","import { type ActionDefinition, arg, defineAction } from \"@venn-lang/sdk\";\nimport { t } from \"@venn-lang/types\";\n\n/**\n * `auth.basic(username, password)`: an `Authorization: Basic …` header.\n *\n * The credentials are base64 of `user:pass`, which is encoding and not secrecy.\n * A password read from `secrets.*` stays redacted in every diagnostic.\n */\nexport const basic: ActionDefinition = defineAction({\n  name: \"basic\",\n  doc: \"Build a Basic Authorization header from a username and password.\",\n  args: [\n    arg(\"username\", t.string, \"Who is signing in.\"),\n    arg(\"password\", t.string, \"Their password. A secret stays redacted.\"),\n  ],\n  result: t.ref(\"auth.Headers\"),\n  run: (_ctx, input) => basicHeader(String(input.args[0] ?? \"\"), String(input.args[1] ?? \"\")),\n});\n\nfunction basicHeader(user: string, pass: string): { Authorization: string } {\n  return { Authorization: `Basic ${btoa(`${user}:${pass}`)}` };\n}\n","import { type ActionDefinition, arg, defineAction } from \"@venn-lang/sdk\";\nimport { t } from \"@venn-lang/types\";\n\n/** `auth.bearer(token)`: an `Authorization: Bearer …` header. Pure, no network. */\nexport const bearer: ActionDefinition = defineAction({\n  name: \"bearer\",\n  doc: \"Build an Authorization header for a bearer token.\",\n  args: [arg(\"token\", t.string, \"The token to carry.\")],\n  result: t.ref(\"auth.Headers\"),\n  run: (_ctx, input) => ({ Authorization: `Bearer ${String(input.args[0] ?? \"\")}` }),\n});\n","// Pure byte encoders shared by the HMAC, TOTP and JWT builders. No I/O and no\n// ports, only deterministic transforms over Web-standard primitives.\n\n/** UTF-8 encode a string. The copy is ArrayBuffer-backed, the only shape WebCrypto accepts. */\nexport function encodeUtf8(text: string): Uint8Array<ArrayBuffer> {\n  return Uint8Array.from(new TextEncoder().encode(text));\n}\n\n/** Lowercase hex of a byte array. */\nexport function toHex(bytes: Uint8Array): string {\n  let out = \"\";\n  for (const byte of bytes) out += byte.toString(16).padStart(2, \"0\");\n  return out;\n}\n\n/** URL-safe, unpadded base64 (base64url) of a byte array. */\nexport function toBase64Url(bytes: Uint8Array): string {\n  let binary = \"\";\n  for (const byte of bytes) binary += String.fromCharCode(byte);\n  return btoa(binary).replace(/\\+/g, \"-\").replace(/\\//g, \"_\").replace(/=+$/, \"\");\n}\n","import { encodeUtf8, toHex } from \"./bytes.js\";\n\nconst ALGOS: Record<string, string> = {\n  sha1: \"SHA-1\",\n  sha256: \"SHA-256\",\n  sha384: \"SHA-384\",\n  sha512: \"SHA-512\",\n};\n\n/**\n * Map whatever the script wrote (`sha256`, `SHA-256`) to a WebCrypto hash name.\n *\n * An unknown label falls back to SHA-256 rather than throwing.\n */\nexport function normalizeHash(algo?: string): string {\n  const key = (algo ?? \"sha256\").toLowerCase().replace(/-/g, \"\");\n  return ALGOS[key] ?? \"SHA-256\";\n}\n\n/** Raw HMAC bytes over `message`, keyed by `secret`, using the global Web Crypto. */\nexport async function hmacRaw(args: {\n  secret: string;\n  message: Uint8Array<ArrayBuffer>;\n  algo?: string;\n}): Promise<Uint8Array> {\n  const key = await crypto.subtle.importKey(\n    \"raw\",\n    encodeUtf8(args.secret),\n    { name: \"HMAC\", hash: normalizeHash(args.algo) },\n    false,\n    [\"sign\"],\n  );\n  const signature = await crypto.subtle.sign(\"HMAC\", key, args.message);\n  return new Uint8Array(signature);\n}\n\n/** Lowercase hex HMAC over a string `payload`, keyed by `secret` (default SHA-256). */\nexport async function hmacHex(args: {\n  secret: string;\n  payload: string;\n  algo?: string;\n}): Promise<string> {\n  return toHex(\n    await hmacRaw({ secret: args.secret, message: encodeUtf8(args.payload), algo: args.algo }),\n  );\n}\n","import { encodeUtf8, toBase64Url } from \"./bytes.js\";\nimport { hmacRaw } from \"./hmac.js\";\n\n/**\n * Sign a compact HS256 JWT.\n *\n * @param args.header Merged over `{ alg: \"HS256\", typ: \"JWT\" }`, so a caller can\n * add claims like `kid` but overriding `alg` does not change how it is signed.\n */\nexport async function signJwt(args: {\n  header?: Record<string, unknown>;\n  payload: unknown;\n  secret: string;\n}): Promise<string> {\n  const header = { alg: \"HS256\", typ: \"JWT\", ...(args.header ?? {}) };\n  const signingInput = `${encodeSegment(header)}.${encodeSegment(args.payload)}`;\n  const signature = await hmacRaw({\n    secret: args.secret,\n    message: encodeUtf8(signingInput),\n    algo: \"sha256\",\n  });\n  return `${signingInput}.${toBase64Url(signature)}`;\n}\n\nfunction encodeSegment(value: unknown): string {\n  return toBase64Url(encodeUtf8(JSON.stringify(value)));\n}\n","import { hmacRaw } from \"./hmac.js\";\n\n/**\n * An RFC 6238 TOTP code: SHA-1, a 30 second period and 6 digits by default.\n *\n * @param args.at The instant to compute for, in seconds. Fixing it fixes the code.\n */\nexport async function totpCode(args: {\n  seed: string;\n  at?: number;\n  period?: number;\n  digits?: number;\n}): Promise<string> {\n  const period = args.period ?? 30;\n  const digits = args.digits ?? 6;\n  const counter = Math.floor((args.at ?? 0) / period);\n  const mac = await hmacRaw({ secret: args.seed, message: counterBytes(counter), algo: \"sha1\" });\n  return truncate({ mac, digits });\n}\n\n/** 8-byte big-endian counter, per HOTP (RFC 4226). */\nfunction counterBytes(counter: number): Uint8Array<ArrayBuffer> {\n  const buffer = new Uint8Array(8);\n  let remaining = counter;\n  for (let i = 7; i >= 0; i -= 1) {\n    buffer[i] = remaining & 0xff;\n    remaining = Math.floor(remaining / 256);\n  }\n  return buffer;\n}\n\n/** Dynamic truncation of an HMAC into a zero-padded decimal code (RFC 4226 §5.3). */\nfunction truncate(args: { mac: Uint8Array; digits: number }): string {\n  const mac = args.mac;\n  const offset = byteAt(mac, mac.length - 1) & 0x0f;\n  const binary =\n    ((byteAt(mac, offset) & 0x7f) << 24) |\n    (byteAt(mac, offset + 1) << 16) |\n    (byteAt(mac, offset + 2) << 8) |\n    byteAt(mac, offset + 3);\n  return String(binary % 10 ** args.digits).padStart(args.digits, \"0\");\n}\n\nfunction byteAt(bytes: Uint8Array, index: number): number {\n  return bytes[index] ?? 0;\n}\n","import { type ActionDefinition, arg, defineAction, z } from \"@venn-lang/sdk\";\nimport { t } from \"@venn-lang/types\";\nimport { hmacHex } from \"../crypto/index.js\";\n\nconst params = z.object({ algo: z.string().optional() }).optional();\n\n/** `auth.hmac(secret, payload, { algo })`: a lowercase hex HMAC. Defaults to SHA-256. */\nexport const hmac: ActionDefinition = defineAction({\n  name: \"hmac\",\n  doc: \"Compute a hex HMAC over a payload using a secret.\",\n  params,\n  args: [arg(\"payload\", t.string, \"What to sign.\"), arg(\"secret\", t.string, \"The shared secret.\")],\n  result: t.string,\n  run: (_ctx, input) =>\n    hmacHex({\n      secret: String(input.args[0] ?? \"\"),\n      payload: String(input.args[1] ?? \"\"),\n      algo: input.params?.algo,\n    }),\n});\n","import { type ActionDefinition, defineAction, z } from \"@venn-lang/sdk\";\nimport { t } from \"@venn-lang/types\";\nimport { signJwt } from \"../crypto/index.js\";\n\nconst params = z.object({\n  header: z.record(z.string(), z.unknown()).optional(),\n  payload: z.unknown(),\n  secret: z.string(),\n});\n\n/** `auth.jwt({ header, payload, secret })`: a compact HS256-signed JWT. */\nexport const jwt: ActionDefinition = defineAction({\n  name: \"jwt\",\n  doc: \"Sign an HS256 JWT.\",\n  params,\n  // Header, payload and secret are all options, so nothing goes positionally.\n  result: t.string,\n  run: (_ctx, input) =>\n    signJwt({\n      header: input.params.header,\n      payload: input.params.payload,\n      secret: input.params.secret,\n    }),\n});\n","import type { Port } from \"@venn-lang/contracts\";\nimport type { AuthClient } from \"./auth-client.types.js\";\n\n/**\n * The port `auth.oauth2` obtains its tokens through.\n *\n * Bound by the host to `createFakeAuthClient` or `createRealAuthClient`.\n * Requires the `net` capability, so a host without it is refused at load time\n * rather than failing mid-run.\n */\nexport const AuthClientPort: Port<AuthClient> = {\n  id: \"venn.port.auth-client\",\n  version: 1,\n  requires: [\"net\"],\n  methods: [\"token\"],\n};\n","import { type ActionDefinition, arg, defineAction, z } from \"@venn-lang/sdk\";\nimport { t } from \"@venn-lang/types\";\nimport { AuthClientPort } from \"../port/index.js\";\n\nconst params = z\n  .object({\n    grant: z.string().optional(),\n    tokenUrl: z.string().optional(),\n    scope: z.string().optional(),\n    refresh: z.string().optional(),\n  })\n  .optional();\n\n/**\n * `auth.oauth2(principal, { grant, tokenUrl, scope, refresh })`: an `auth.Token`.\n *\n * The only verb here that leaves the process, and it does so through\n * `AuthClientPort` rather than calling the endpoint itself.\n */\nexport const oauth2: ActionDefinition = defineAction({\n  name: \"oauth2\",\n  doc: \"Obtain an OAuth2 token for a principal via the AuthClient port.\",\n  params,\n  args: [arg(\"principal\", t.string, \"Who the token is for.\")],\n  result: t.ref(\"auth.Token\"),\n  run: (ctx, input) =>\n    ctx.port(AuthClientPort).token({\n      principal: String(input.args[0] ?? \"\"),\n      grant: input.params?.grant,\n      tokenUrl: input.params?.tokenUrl,\n      scope: input.params?.scope,\n      refresh: input.params?.refresh,\n    }),\n});\n","import { type ActionDefinition, arg, defineAction, z } from \"@venn-lang/sdk\";\nimport { t } from \"@venn-lang/types\";\nimport { totpCode } from \"../crypto/index.js\";\n\nconst params = z\n  .object({\n    at: z.number().optional(),\n    period: z.number().optional(),\n    digits: z.number().optional(),\n  })\n  .optional();\n\n/**\n * `auth.totp(seed, { at, period, digits })`: an RFC 6238 one-time code.\n *\n * Pin `at` to a fixed instant to get the same code on every run.\n */\nexport const totp: ActionDefinition = defineAction({\n  name: \"totp\",\n  doc: \"Compute a TOTP code from a shared seed.\",\n  params,\n  // A code is digits, but it is written and compared as text: leading zeros are\n  // part of it, so the result is a string and not a number.\n  args: [arg(\"seed\", t.string, \"The shared seed, base32.\")],\n  result: t.string,\n  run: (_ctx, input) =>\n    totpCode({\n      seed: String(input.args[0] ?? \"\"),\n      at: input.params?.at,\n      period: input.params?.period,\n      digits: input.params?.digits,\n    }),\n});\n","import type { ActionDefinition } from \"@venn-lang/sdk\";\nimport { apikey } from \"./apikey.js\";\nimport { basic } from \"./basic.js\";\nimport { bearer } from \"./bearer.js\";\nimport { hmac } from \"./hmac.js\";\nimport { jwt } from \"./jwt.js\";\nimport { oauth2 } from \"./oauth2.js\";\nimport { totp } from \"./totp.js\";\n\n/** The auth namespace's verbs. Adding one is a single line here. */\nexport const authActions: ActionDefinition[] = [bearer, basic, apikey, hmac, totp, jwt, oauth2];\n","import type { AuthClient, OAuthToken } from \"../port/index.js\";\n\n/**\n * The in-process `AuthClient`: a canned token derived from the principal, no network.\n *\n * @param args.token Fields to override on every token it hands back.\n */\nexport function createFakeAuthClient(args: { token?: Partial<OAuthToken> } = {}): AuthClient {\n  return {\n    token: async (request) => ({\n      access_token: `fake-access-token:${request.principal}`,\n      token_type: \"Bearer\",\n      expires_in: 3600,\n      ...args.token,\n    }),\n  };\n}\n","import { VennError } from \"@venn-lang/contracts\";\nimport type { AuthClient } from \"../port/index.js\";\n\n/**\n * The endpoint-backed `AuthClient`. Not implemented in this build.\n *\n * @throws VennError `VN8090` on every call, so a host that binds it fails loudly\n * instead of quietly handing a script a token that was never obtained.\n */\nexport function createRealAuthClient(): AuthClient {\n  return {\n    token: async () => {\n      throw new VennError({\n        code: \"VN8090\",\n        message: \"OAuth2 real client not implemented in this build\",\n      });\n    },\n  };\n}\n","import { type ZodType, z } from \"@venn-lang/sdk\";\n\n/** Runtime schema for the nominal `Token` type, the value `auth.oauth2` yields. */\nexport const Token: ZodType = z.object({\n  access_token: z.string(),\n  token_type: z.string(),\n  expires_in: z.number(),\n});\n","import { type TypeSpec, t } from \"@venn-lang/types\";\n\n/**\n * The named types `@venn-lang/auth` publishes to scripts, keyed by their bare name.\n *\n * `Token` restates `OAuthToken` in `port/auth-client.types.ts` and, field for\n * field, the Zod `Token` next door. Each serves a different reader: Zod checks a\n * value that arrived, this types a call being written. Change all three together.\n */\nexport const authTypeDefs: Readonly<Record<string, TypeSpec>> = {\n  /**\n   * What the header builders hand back, ready to go into a request's `headers`.\n   *\n   * A map rather than a record: `auth.apikey` names its own header, so the key\n   * is only known at the call. The values are always strings.\n   */\n  Headers: t.map(t.string),\n  /** An OAuth2 token, as the token endpoint answered with it. */\n  Token: t.record({\n    access_token: t.string,\n    token_type: t.string,\n    expires_in: t.number,\n  }),\n};\n","import { definePlugin, type PluginDefinition } from \"@venn-lang/sdk\";\nimport { authActions } from \"./actions/index.js\";\nimport { authTypeDefs, Token } from \"./types/index.js\";\n\n/**\n * The `auth` plugin: header builders, signing helpers and an OAuth2 exchange.\n *\n * Every verb but `auth.oauth2` is pure. That one reaches out through\n * `AuthClientPort`, which is why the whole plugin declares the `net` capability\n * and is refused at load time on a host that cannot offer it.\n */\nexport const authPlugin: PluginDefinition = definePlugin({\n  name: \"venn/auth\",\n  version: \"0.0.0\",\n  namespace: \"auth\",\n  requires: [\"net\"],\n  actions: authActions,\n  types: { Token },\n  typeDefs: authTypeDefs,\n});\n\nexport { authPlugin as default };\n"],"mappings":";;;;;;;;AAUA,MAAa,SAA2B,aAAa;CACnD,MAAM;CACN,KAAK;CACL,QAVa,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,SAUzD;CACA,MAAM,CAAC,IAAI,OAAO,EAAE,QAAQ,qBAAqB,CAAC;CAClD,QAAQ,EAAE,IAAI,cAAc;CAC5B,MAAM,MAAM,UAAU;EAEpB,OAAO,GADQ,MAAM,QAAQ,UAAU,cACpB,OAAO,MAAM,KAAK,MAAM,EAAE,EAAE;CACjD;AACF,CAAC;;;;;;;;;ACXD,MAAa,QAA0B,aAAa;CAClD,MAAM;CACN,KAAK;CACL,MAAM,CACJ,IAAI,YAAY,EAAE,QAAQ,oBAAoB,GAC9C,IAAI,YAAY,EAAE,QAAQ,0CAA0C,CACtE;CACA,QAAQ,EAAE,IAAI,cAAc;CAC5B,MAAM,MAAM,UAAU,YAAY,OAAO,MAAM,KAAK,MAAM,EAAE,GAAG,OAAO,MAAM,KAAK,MAAM,EAAE,CAAC;AAC5F,CAAC;AAED,SAAS,YAAY,MAAc,MAAyC;CAC1E,OAAO,EAAE,eAAe,SAAS,KAAK,GAAG,KAAK,GAAG,MAAM,IAAI;AAC7D;;;;AClBA,MAAa,SAA2B,aAAa;CACnD,MAAM;CACN,KAAK;CACL,MAAM,CAAC,IAAI,SAAS,EAAE,QAAQ,qBAAqB,CAAC;CACpD,QAAQ,EAAE,IAAI,cAAc;CAC5B,MAAM,MAAM,WAAW,EAAE,eAAe,UAAU,OAAO,MAAM,KAAK,MAAM,EAAE,IAAI;AAClF,CAAC;;;;ACND,SAAgB,WAAW,MAAuC;CAChE,OAAO,WAAW,KAAK,IAAI,YAAY,CAAC,CAAC,OAAO,IAAI,CAAC;AACvD;;AAGA,SAAgB,MAAM,OAA2B;CAC/C,IAAI,MAAM;CACV,KAAK,MAAM,QAAQ,OAAO,OAAO,KAAK,SAAS,EAAE,CAAC,CAAC,SAAS,GAAG,GAAG;CAClE,OAAO;AACT;;AAGA,SAAgB,YAAY,OAA2B;CACrD,IAAI,SAAS;CACb,KAAK,MAAM,QAAQ,OAAO,UAAU,OAAO,aAAa,IAAI;CAC5D,OAAO,KAAK,MAAM,CAAC,CAAC,QAAQ,OAAO,GAAG,CAAC,CAAC,QAAQ,OAAO,GAAG,CAAC,CAAC,QAAQ,OAAO,EAAE;AAC/E;;;AClBA,MAAM,QAAgC;CACpC,MAAM;CACN,QAAQ;CACR,QAAQ;CACR,QAAQ;AACV;;;;;;AAOA,SAAgB,cAAc,MAAuB;CACnD,MAAM,OAAO,QAAQ,SAAA,CAAU,YAAY,CAAC,CAAC,QAAQ,MAAM,EAAE;CAC7D,OAAO,MAAM,QAAQ;AACvB;;AAGA,eAAsB,QAAQ,MAIN;CACtB,MAAM,MAAM,MAAM,OAAO,OAAO,UAC9B,OACA,WAAW,KAAK,MAAM,GACtB;EAAE,MAAM;EAAQ,MAAM,cAAc,KAAK,IAAI;CAAE,GAC/C,OACA,CAAC,MAAM,CACT;CACA,MAAM,YAAY,MAAM,OAAO,OAAO,KAAK,QAAQ,KAAK,KAAK,OAAO;CACpE,OAAO,IAAI,WAAW,SAAS;AACjC;;AAGA,eAAsB,QAAQ,MAIV;CAClB,OAAO,MACL,MAAM,QAAQ;EAAE,QAAQ,KAAK;EAAQ,SAAS,WAAW,KAAK,OAAO;EAAG,MAAM,KAAK;CAAK,CAAC,CAC3F;AACF;;;;;;;;;ACpCA,eAAsB,QAAQ,MAIV;CAElB,MAAM,eAAe,GAAG,cAAc;EADrB,KAAK;EAAS,KAAK;EAAO,GAAI,KAAK,UAAU,CAAC;CACpB,CAAC,EAAE,GAAG,cAAc,KAAK,OAAO;CAM3E,OAAO,GAAG,aAAa,GAAG,YAAY,MALd,QAAQ;EAC9B,QAAQ,KAAK;EACb,SAAS,WAAW,YAAY;EAChC,MAAM;CACR,CAAC,CAC8C;AACjD;AAEA,SAAS,cAAc,OAAwB;CAC7C,OAAO,YAAY,WAAW,KAAK,UAAU,KAAK,CAAC,CAAC;AACtD;;;;;;;;ACnBA,eAAsB,SAAS,MAKX;CAClB,MAAM,SAAS,KAAK,UAAU;CAC9B,MAAM,SAAS,KAAK,UAAU;CAC9B,MAAM,UAAU,KAAK,OAAO,KAAK,MAAM,KAAK,MAAM;CAElD,OAAO,SAAS;EAAE,KAAA,MADA,QAAQ;GAAE,QAAQ,KAAK;GAAM,SAAS,aAAa,OAAO;GAAG,MAAM;EAAO,CAAC;EACtE;CAAO,CAAC;AACjC;;AAGA,SAAS,aAAa,SAA0C;CAC9D,MAAM,yBAAS,IAAI,WAAW,CAAC;CAC/B,IAAI,YAAY;CAChB,KAAK,IAAI,IAAI,GAAG,KAAK,GAAG,KAAK,GAAG;EAC9B,OAAO,KAAK,YAAY;EACxB,YAAY,KAAK,MAAM,YAAY,GAAG;CACxC;CACA,OAAO;AACT;;AAGA,SAAS,SAAS,MAAmD;CACnE,MAAM,MAAM,KAAK;CACjB,MAAM,SAAS,OAAO,KAAK,IAAI,SAAS,CAAC,IAAI;CAC7C,MAAM,UACF,OAAO,KAAK,MAAM,IAAI,QAAS,KAChC,OAAO,KAAK,SAAS,CAAC,KAAK,KAC3B,OAAO,KAAK,SAAS,CAAC,KAAK,IAC5B,OAAO,KAAK,SAAS,CAAC;CACxB,OAAO,OAAO,SAAS,MAAM,KAAK,MAAM,CAAC,CAAC,SAAS,KAAK,QAAQ,GAAG;AACrE;AAEA,SAAS,OAAO,OAAmB,OAAuB;CACxD,OAAO,MAAM,UAAU;AACzB;;ACtCA,MAAa,OAAyB,aAAa;CACjD,MAAM;CACN,KAAK;CACL,QANa,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,SAMvD;CACA,MAAM,CAAC,IAAI,WAAW,EAAE,QAAQ,eAAe,GAAG,IAAI,UAAU,EAAE,QAAQ,oBAAoB,CAAC;CAC/F,QAAQ,EAAE;CACV,MAAM,MAAM,UACV,QAAQ;EACN,QAAQ,OAAO,MAAM,KAAK,MAAM,EAAE;EAClC,SAAS,OAAO,MAAM,KAAK,MAAM,EAAE;EACnC,MAAM,MAAM,QAAQ;CACtB,CAAC;AACL,CAAC;;ACRD,MAAa,MAAwB,aAAa;CAChD,MAAM;CACN,KAAK;CACL,QAVa,EAAE,OAAO;EACtB,QAAQ,EAAE,OAAO,EAAE,OAAO,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC,SAAS;EACnD,SAAS,EAAE,QAAQ;EACnB,QAAQ,EAAE,OAAO;CACnB,CAME;CAEA,QAAQ,EAAE;CACV,MAAM,MAAM,UACV,QAAQ;EACN,QAAQ,MAAM,OAAO;EACrB,SAAS,MAAM,OAAO;EACtB,QAAQ,MAAM,OAAO;CACvB,CAAC;AACL,CAAC;;;;;;;;;;ACbD,MAAa,iBAAmC;CAC9C,IAAI;CACJ,SAAS;CACT,UAAU,CAAC,KAAK;CAChB,SAAS,CAAC,OAAO;AACnB;;;;;;;ACIA,MAAa,SAA2B,aAAa;CACnD,MAAM;CACN,KAAK;CACL,QAlBa,EACZ,OAAO;EACN,OAAO,EAAE,OAAO,CAAC,CAAC,SAAS;EAC3B,UAAU,EAAE,OAAO,CAAC,CAAC,SAAS;EAC9B,OAAO,EAAE,OAAO,CAAC,CAAC,SAAS;EAC3B,SAAS,EAAE,OAAO,CAAC,CAAC,SAAS;CAC/B,CAAC,CAAC,CACD,SAWD;CACA,MAAM,CAAC,IAAI,aAAa,EAAE,QAAQ,uBAAuB,CAAC;CAC1D,QAAQ,EAAE,IAAI,YAAY;CAC1B,MAAM,KAAK,UACT,IAAI,KAAK,cAAc,CAAC,CAAC,MAAM;EAC7B,WAAW,OAAO,MAAM,KAAK,MAAM,EAAE;EACrC,OAAO,MAAM,QAAQ;EACrB,UAAU,MAAM,QAAQ;EACxB,OAAO,MAAM,QAAQ;EACrB,SAAS,MAAM,QAAQ;CACzB,CAAC;AACL,CAAC;;;;AEvBD,MAAa,cAAkC;CAAC;CAAQ;CAAO;CAAQ;CDOjC,aAAa;EACjD,MAAM;EACN,KAAK;EACL,QAhBa,EACZ,OAAO;GACN,IAAI,EAAE,OAAO,CAAC,CAAC,SAAS;GACxB,QAAQ,EAAE,OAAO,CAAC,CAAC,SAAS;GAC5B,QAAQ,EAAE,OAAO,CAAC,CAAC,SAAS;EAC9B,CAAC,CAAC,CACD,SAUD;EAGA,MAAM,CAAC,IAAI,QAAQ,EAAE,QAAQ,0BAA0B,CAAC;EACxD,QAAQ,EAAE;EACV,MAAM,MAAM,UACV,SAAS;GACP,MAAM,OAAO,MAAM,KAAK,MAAM,EAAE;GAChC,IAAI,MAAM,QAAQ;GAClB,QAAQ,MAAM,QAAQ;GACtB,QAAQ,MAAM,QAAQ;EACxB,CAAC;CACL,CCtB6E;CAAM;CAAK;AAAM;;;;;;;;ACH9F,SAAgB,qBAAqB,OAAwC,CAAC,GAAe;CAC3F,OAAO,EACL,OAAO,OAAO,aAAa;EACzB,cAAc,qBAAqB,QAAQ;EAC3C,YAAY;EACZ,YAAY;EACZ,GAAG,KAAK;CACV,GACF;AACF;;;;;;;;;ACPA,SAAgB,uBAAmC;CACjD,OAAO,EACL,OAAO,YAAY;EACjB,MAAM,IAAI,UAAU;GAClB,MAAM;GACN,SAAS;EACX,CAAC;CACH,EACF;AACF;;;;ACfA,MAAa,QAAiB,EAAE,OAAO;CACrC,cAAc,EAAE,OAAO;CACvB,YAAY,EAAE,OAAO;CACrB,YAAY,EAAE,OAAO;AACvB,CAAC;;;;;;;;;;ACED,MAAa,eAAmD;;;;;;;CAO9D,SAAS,EAAE,IAAI,EAAE,MAAM;;CAEvB,OAAO,EAAE,OAAO;EACd,cAAc,EAAE;EAChB,YAAY,EAAE;EACd,YAAY,EAAE;CAChB,CAAC;AACH;;;;;;;;;;ACZA,MAAa,aAA+B,aAAa;CACvD,MAAM;CACN,SAAS;CACT,WAAW;CACX,UAAU,CAAC,KAAK;CAChB,SAAS;CACT,OAAO,EAAE,MAAM;CACf,UAAU;AACZ,CAAC"}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@venn-lang/auth",
+  "version": "0.1.0",
+  "description": "The auth namespace: build the header a request needs, or fetch a token for it.",
+  "keywords": [
+    "venn",
+    "testing",
+    "e2e",
+    "auth"
+  ],
+  "homepage": "https://github.com/venn-lang/venn/tree/main/packages/std-auth#readme",
+  "bugs": "https://github.com/venn-lang/venn/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/venn-lang/venn.git",
+    "directory": "packages/std-auth"
+  },
+  "license": "MIT",
+  "author": "Vinicius Borges",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.suite.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@venn-lang/contracts": "0.1.0",
+    "@venn-lang/sdk": "0.1.0",
+    "@venn-lang/types": "0.1.0"
+  },
+  "devDependencies": {
+    "tsdown": "^0.22.14",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/actions/apikey.ts

@@ -0,0 +1,21 @@
+import { type ActionDefinition, arg, defineAction, z } from "@venn-lang/sdk";
+import { t } from "@venn-lang/types";
+
+const params = z.object({ header: z.string().optional() }).optional();
+
+/**
+ * `auth.apikey(key, { header })`: a one-entry header object carrying an API key.
+ *
+ * The header name defaults to `X-API-Key`. Pure, no network.
+ */
+export const apikey: ActionDefinition = defineAction({
+  name: "apikey",
+  doc: "Build a header object carrying an API key.",
+  params,
+  args: [arg("key", t.string, "The API key itself.")],
+  result: t.ref("auth.Headers"),
+  run: (_ctx, input) => {
+    const header = input.params?.header ?? "X-API-Key";
+    return { [header]: String(input.args[0] ?? "") };
+  },
+});

package/src/actions/basic.ts

@@ -0,0 +1,23 @@
+import { type ActionDefinition, arg, defineAction } from "@venn-lang/sdk";
+import { t } from "@venn-lang/types";
+
+/**
+ * `auth.basic(username, password)`: an `Authorization: Basic …` header.
+ *
+ * The credentials are base64 of `user:pass`, which is encoding and not secrecy.
+ * A password read from `secrets.*` stays redacted in every diagnostic.
+ */
+export const basic: ActionDefinition = defineAction({
+  name: "basic",
+  doc: "Build a Basic Authorization header from a username and password.",
+  args: [
+    arg("username", t.string, "Who is signing in."),
+    arg("password", t.string, "Their password. A secret stays redacted."),
+  ],
+  result: t.ref("auth.Headers"),
+  run: (_ctx, input) => basicHeader(String(input.args[0] ?? ""), String(input.args[1] ?? "")),
+});
+
+function basicHeader(user: string, pass: string): { Authorization: string } {
+  return { Authorization: `Basic ${btoa(`${user}:${pass}`)}` };
+}

package/src/actions/bearer.ts

@@ -0,0 +1,11 @@
+import { type ActionDefinition, arg, defineAction } from "@venn-lang/sdk";
+import { t } from "@venn-lang/types";
+
+/** `auth.bearer(token)`: an `Authorization: Bearer …` header. Pure, no network. */
+export const bearer: ActionDefinition = defineAction({
+  name: "bearer",
+  doc: "Build an Authorization header for a bearer token.",
+  args: [arg("token", t.string, "The token to carry.")],
+  result: t.ref("auth.Headers"),
+  run: (_ctx, input) => ({ Authorization: `Bearer ${String(input.args[0] ?? "")}` }),
+});

package/src/actions/hmac.ts

@@ -0,0 +1,20 @@
+import { type ActionDefinition, arg, defineAction, z } from "@venn-lang/sdk";
+import { t } from "@venn-lang/types";
+import { hmacHex } from "../crypto/index.js";
+
+const params = z.object({ algo: z.string().optional() }).optional();
+
+/** `auth.hmac(secret, payload, { algo })`: a lowercase hex HMAC. Defaults to SHA-256. */
+export const hmac: ActionDefinition = defineAction({
+  name: "hmac",
+  doc: "Compute a hex HMAC over a payload using a secret.",
+  params,
+  args: [arg("payload", t.string, "What to sign."), arg("secret", t.string, "The shared secret.")],
+  result: t.string,
+  run: (_ctx, input) =>
+    hmacHex({
+      secret: String(input.args[0] ?? ""),
+      payload: String(input.args[1] ?? ""),
+      algo: input.params?.algo,
+    }),
+});

package/src/actions/index.ts

@@ -0,0 +1,11 @@
+import type { ActionDefinition } from "@venn-lang/sdk";
+import { apikey } from "./apikey.js";
+import { basic } from "./basic.js";
+import { bearer } from "./bearer.js";
+import { hmac } from "./hmac.js";
+import { jwt } from "./jwt.js";
+import { oauth2 } from "./oauth2.js";
+import { totp } from "./totp.js";
+
+/** The auth namespace's verbs. Adding one is a single line here. */
+export const authActions: ActionDefinition[] = [bearer, basic, apikey, hmac, totp, jwt, oauth2];

package/src/actions/jwt.ts

@@ -0,0 +1,24 @@
+import { type ActionDefinition, defineAction, z } from "@venn-lang/sdk";
+import { t } from "@venn-lang/types";
+import { signJwt } from "../crypto/index.js";
+
+const params = z.object({
+  header: z.record(z.string(), z.unknown()).optional(),
+  payload: z.unknown(),
+  secret: z.string(),
+});
+
+/** `auth.jwt({ header, payload, secret })`: a compact HS256-signed JWT. */
+export const jwt: ActionDefinition = defineAction({
+  name: "jwt",
+  doc: "Sign an HS256 JWT.",
+  params,
+  // Header, payload and secret are all options, so nothing goes positionally.
+  result: t.string,
+  run: (_ctx, input) =>
+    signJwt({
+      header: input.params.header,
+      payload: input.params.payload,
+      secret: input.params.secret,
+    }),
+});

package/src/actions/oauth2.ts

@@ -0,0 +1,34 @@
+import { type ActionDefinition, arg, defineAction, z } from "@venn-lang/sdk";
+import { t } from "@venn-lang/types";
+import { AuthClientPort } from "../port/index.js";
+
+const params = z
+  .object({
+    grant: z.string().optional(),
+    tokenUrl: z.string().optional(),
+    scope: z.string().optional(),
+    refresh: z.string().optional(),
+  })
+  .optional();
+
+/**
+ * `auth.oauth2(principal, { grant, tokenUrl, scope, refresh })`: an `auth.Token`.
+ *
+ * The only verb here that leaves the process, and it does so through
+ * `AuthClientPort` rather than calling the endpoint itself.
+ */
+export const oauth2: ActionDefinition = defineAction({
+  name: "oauth2",
+  doc: "Obtain an OAuth2 token for a principal via the AuthClient port.",
+  params,
+  args: [arg("principal", t.string, "Who the token is for.")],
+  result: t.ref("auth.Token"),
+  run: (ctx, input) =>
+    ctx.port(AuthClientPort).token({
+      principal: String(input.args[0] ?? ""),
+      grant: input.params?.grant,
+      tokenUrl: input.params?.tokenUrl,
+      scope: input.params?.scope,
+      refresh: input.params?.refresh,
+    }),
+});

package/src/actions/totp.ts

@@ -0,0 +1,33 @@
+import { type ActionDefinition, arg, defineAction, z } from "@venn-lang/sdk";
+import { t } from "@venn-lang/types";
+import { totpCode } from "../crypto/index.js";
+
+const params = z
+  .object({
+    at: z.number().optional(),
+    period: z.number().optional(),
+    digits: z.number().optional(),
+  })
+  .optional();
+
+/**
+ * `auth.totp(seed, { at, period, digits })`: an RFC 6238 one-time code.
+ *
+ * Pin `at` to a fixed instant to get the same code on every run.
+ */
+export const totp: ActionDefinition = defineAction({
+  name: "totp",
+  doc: "Compute a TOTP code from a shared seed.",
+  params,
+  // A code is digits, but it is written and compared as text: leading zeros are
+  // part of it, so the result is a string and not a number.
+  args: [arg("seed", t.string, "The shared seed, base32.")],
+  result: t.string,
+  run: (_ctx, input) =>
+    totpCode({
+      seed: String(input.args[0] ?? ""),
+      at: input.params?.at,
+      period: input.params?.period,
+      digits: input.params?.digits,
+    }),
+});

package/src/clients/fake-client.ts

@@ -0,0 +1,17 @@
+import type { AuthClient, OAuthToken } from "../port/index.js";
+
+/**
+ * The in-process `AuthClient`: a canned token derived from the principal, no network.
+ *
+ * @param args.token Fields to override on every token it hands back.
+ */
+export function createFakeAuthClient(args: { token?: Partial<OAuthToken> } = {}): AuthClient {
+  return {
+    token: async (request) => ({
+      access_token: `fake-access-token:${request.principal}`,
+      token_type: "Bearer",
+      expires_in: 3600,
+      ...args.token,
+    }),
+  };
+}

package/src/clients/index.ts

@@ -0,0 +1,2 @@
+export { createFakeAuthClient } from "./fake-client.js";
+export { createRealAuthClient } from "./real-client.js";

package/src/clients/real-client.ts

@@ -0,0 +1,19 @@
+import { VennError } from "@venn-lang/contracts";
+import type { AuthClient } from "../port/index.js";
+
+/**
+ * The endpoint-backed `AuthClient`. Not implemented in this build.
+ *
+ * @throws VennError `VN8090` on every call, so a host that binds it fails loudly
+ * instead of quietly handing a script a token that was never obtained.
+ */
+export function createRealAuthClient(): AuthClient {
+  return {
+    token: async () => {
+      throw new VennError({
+        code: "VN8090",
+        message: "OAuth2 real client not implemented in this build",
+      });
+    },
+  };
+}

package/src/crypto/bytes.ts

@@ -0,0 +1,21 @@
+// Pure byte encoders shared by the HMAC, TOTP and JWT builders. No I/O and no
+// ports, only deterministic transforms over Web-standard primitives.
+
+/** UTF-8 encode a string. The copy is ArrayBuffer-backed, the only shape WebCrypto accepts. */
+export function encodeUtf8(text: string): Uint8Array<ArrayBuffer> {
+  return Uint8Array.from(new TextEncoder().encode(text));
+}
+
+/** Lowercase hex of a byte array. */
+export function toHex(bytes: Uint8Array): string {
+  let out = "";
+  for (const byte of bytes) out += byte.toString(16).padStart(2, "0");
+  return out;
+}
+
+/** URL-safe, unpadded base64 (base64url) of a byte array. */
+export function toBase64Url(bytes: Uint8Array): string {
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}

package/src/crypto/hmac.ts

@@ -0,0 +1,46 @@
+import { encodeUtf8, toHex } from "./bytes.js";
+
+const ALGOS: Record<string, string> = {
+  sha1: "SHA-1",
+  sha256: "SHA-256",
+  sha384: "SHA-384",
+  sha512: "SHA-512",
+};
+
+/**
+ * Map whatever the script wrote (`sha256`, `SHA-256`) to a WebCrypto hash name.
+ *
+ * An unknown label falls back to SHA-256 rather than throwing.
+ */
+export function normalizeHash(algo?: string): string {
+  const key = (algo ?? "sha256").toLowerCase().replace(/-/g, "");
+  return ALGOS[key] ?? "SHA-256";
+}
+
+/** Raw HMAC bytes over `message`, keyed by `secret`, using the global Web Crypto. */
+export async function hmacRaw(args: {
+  secret: string;
+  message: Uint8Array<ArrayBuffer>;
+  algo?: string;
+}): Promise<Uint8Array> {
+  const key = await crypto.subtle.importKey(
+    "raw",
+    encodeUtf8(args.secret),
+    { name: "HMAC", hash: normalizeHash(args.algo) },
+    false,
+    ["sign"],
+  );
+  const signature = await crypto.subtle.sign("HMAC", key, args.message);
+  return new Uint8Array(signature);
+}
+
+/** Lowercase hex HMAC over a string `payload`, keyed by `secret` (default SHA-256). */
+export async function hmacHex(args: {
+  secret: string;
+  payload: string;
+  algo?: string;
+}): Promise<string> {
+  return toHex(
+    await hmacRaw({ secret: args.secret, message: encodeUtf8(args.payload), algo: args.algo }),
+  );
+}

package/src/crypto/index.ts

@@ -0,0 +1,4 @@
+export { encodeUtf8, toBase64Url, toHex } from "./bytes.js";
+export { hmacHex, hmacRaw, normalizeHash } from "./hmac.js";
+export { signJwt } from "./jwt.js";
+export { totpCode } from "./totp.js";

package/src/crypto/jwt.ts

@@ -0,0 +1,27 @@
+import { encodeUtf8, toBase64Url } from "./bytes.js";
+import { hmacRaw } from "./hmac.js";
+
+/**
+ * Sign a compact HS256 JWT.
+ *
+ * @param args.header Merged over `{ alg: "HS256", typ: "JWT" }`, so a caller can
+ * add claims like `kid` but overriding `alg` does not change how it is signed.
+ */
+export async function signJwt(args: {
+  header?: Record<string, unknown>;
+  payload: unknown;
+  secret: string;
+}): Promise<string> {
+  const header = { alg: "HS256", typ: "JWT", ...(args.header ?? {}) };
+  const signingInput = `${encodeSegment(header)}.${encodeSegment(args.payload)}`;
+  const signature = await hmacRaw({
+    secret: args.secret,
+    message: encodeUtf8(signingInput),
+    algo: "sha256",
+  });
+  return `${signingInput}.${toBase64Url(signature)}`;
+}
+
+function encodeSegment(value: unknown): string {
+  return toBase64Url(encodeUtf8(JSON.stringify(value)));
+}

package/src/crypto/totp.ts

@@ -0,0 +1,46 @@
+import { hmacRaw } from "./hmac.js";
+
+/**
+ * An RFC 6238 TOTP code: SHA-1, a 30 second period and 6 digits by default.
+ *
+ * @param args.at The instant to compute for, in seconds. Fixing it fixes the code.
+ */
+export async function totpCode(args: {
+  seed: string;
+  at?: number;
+  period?: number;
+  digits?: number;
+}): Promise<string> {
+  const period = args.period ?? 30;
+  const digits = args.digits ?? 6;
+  const counter = Math.floor((args.at ?? 0) / period);
+  const mac = await hmacRaw({ secret: args.seed, message: counterBytes(counter), algo: "sha1" });
+  return truncate({ mac, digits });
+}
+
+/** 8-byte big-endian counter, per HOTP (RFC 4226). */
+function counterBytes(counter: number): Uint8Array<ArrayBuffer> {
+  const buffer = new Uint8Array(8);
+  let remaining = counter;
+  for (let i = 7; i >= 0; i -= 1) {
+    buffer[i] = remaining & 0xff;
+    remaining = Math.floor(remaining / 256);
+  }
+  return buffer;
+}
+
+/** Dynamic truncation of an HMAC into a zero-padded decimal code (RFC 4226 §5.3). */
+function truncate(args: { mac: Uint8Array; digits: number }): string {
+  const mac = args.mac;
+  const offset = byteAt(mac, mac.length - 1) & 0x0f;
+  const binary =
+    ((byteAt(mac, offset) & 0x7f) << 24) |
+    (byteAt(mac, offset + 1) << 16) |
+    (byteAt(mac, offset + 2) << 8) |
+    byteAt(mac, offset + 3);
+  return String(binary % 10 ** args.digits).padStart(args.digits, "0");
+}
+
+function byteAt(bytes: Uint8Array, index: number): number {
+  return bytes[index] ?? 0;
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+// @venn-lang/auth: pure token and header builders (bearer, basic, apikey, hmac, totp,
+// jwt), plus `oauth2`, which rides the AuthClient port so a live token exchange is
+// injected rather than baked in. Signing uses the global Web Crypto.
+
+export * from "./actions/index.js";
+export * from "./clients/index.js";
+export { authPlugin, authPlugin as default } from "./plugin.js";
+export * from "./port/index.js";
+export * from "./types/index.js";

package/src/plugin.ts

@@ -0,0 +1,22 @@
+import { definePlugin, type PluginDefinition } from "@venn-lang/sdk";
+import { authActions } from "./actions/index.js";
+import { authTypeDefs, Token } from "./types/index.js";
+
+/**
+ * The `auth` plugin: header builders, signing helpers and an OAuth2 exchange.
+ *
+ * Every verb but `auth.oauth2` is pure. That one reaches out through
+ * `AuthClientPort`, which is why the whole plugin declares the `net` capability
+ * and is refused at load time on a host that cannot offer it.
+ */
+export const authPlugin: PluginDefinition = definePlugin({
+  name: "venn/auth",
+  version: "0.0.0",
+  namespace: "auth",
+  requires: ["net"],
+  actions: authActions,
+  types: { Token },
+  typeDefs: authTypeDefs,
+});
+
+export { authPlugin as default };

package/src/port/auth-client.port.ts

@@ -0,0 +1,16 @@
+import type { Port } from "@venn-lang/contracts";
+import type { AuthClient } from "./auth-client.types.js";
+
+/**
+ * The port `auth.oauth2` obtains its tokens through.
+ *
+ * Bound by the host to `createFakeAuthClient` or `createRealAuthClient`.
+ * Requires the `net` capability, so a host without it is refused at load time
+ * rather than failing mid-run.
+ */
+export const AuthClientPort: Port<AuthClient> = {
+  id: "venn.port.auth-client",
+  version: 1,
+  requires: ["net"],
+  methods: ["token"],
+};

package/src/port/auth-client.types.ts

@@ -0,0 +1,24 @@
+/** Arguments for {@link AuthClient.token}: which principal, and how to obtain or refresh it. */
+export interface OAuthTokenRequest {
+  principal: string;
+  grant?: string;
+  tokenUrl?: string;
+  scope?: string;
+  refresh?: string;
+}
+
+/** A token as the endpoint answered with it. Snake case, because that is the wire shape. */
+export interface OAuthToken {
+  access_token: string;
+  token_type: string;
+  expires_in: number;
+}
+
+/**
+ * The contract `auth.oauth2` acquires tokens through.
+ *
+ * Reached via `ctx.port(AuthClientPort)`, never by calling an endpoint directly.
+ */
+export interface AuthClient {
+  token(request: OAuthTokenRequest): Promise<OAuthToken>;
+}

package/src/port/index.ts

@@ -0,0 +1,2 @@
+export { AuthClientPort } from "./auth-client.port.js";
+export type { AuthClient, OAuthToken, OAuthTokenRequest } from "./auth-client.types.js";

package/src/types/index.ts

@@ -0,0 +1,2 @@
+export { Token } from "./token.js";
+export { authTypeDefs } from "./type-defs.js";

package/src/types/token.ts

@@ -0,0 +1,8 @@
+import { type ZodType, z } from "@venn-lang/sdk";
+
+/** Runtime schema for the nominal `Token` type, the value `auth.oauth2` yields. */
+export const Token: ZodType = z.object({
+  access_token: z.string(),
+  token_type: z.string(),
+  expires_in: z.number(),
+});

package/src/types/type-defs.ts

@@ -0,0 +1,24 @@
+import { type TypeSpec, t } from "@venn-lang/types";
+
+/**
+ * The named types `@venn-lang/auth` publishes to scripts, keyed by their bare name.
+ *
+ * `Token` restates `OAuthToken` in `port/auth-client.types.ts` and, field for
+ * field, the Zod `Token` next door. Each serves a different reader: Zod checks a
+ * value that arrived, this types a call being written. Change all three together.
+ */
+export const authTypeDefs: Readonly<Record<string, TypeSpec>> = {
+  /**
+   * What the header builders hand back, ready to go into a request's `headers`.
+   *
+   * A map rather than a record: `auth.apikey` names its own header, so the key
+   * is only known at the call. The values are always strings.
+   */
+  Headers: t.map(t.string),
+  /** An OAuth2 token, as the token endpoint answered with it. */
+  Token: t.record({
+    access_token: t.string,
+    token_type: t.string,
+    expires_in: t.number,
+  }),
+};