@owlmeans/test-auth 0.1.7 → 0.1.8

package/README.md

@@ -11,3 +11,20 @@ Helpers exported here:
 - `signMockEnvelope(msg, type, kind?, kp?)` — wraps `makeEnvelopeModel` with a fixture keypair to produce a signed envelope.
 - `makeBearer(auth, kp?)` — `ED25519-BASIC-TOKEN <encoded>` header value for unit tests of header parsing.
 - Canonical fixtures: `SUPERUSER`, `USER`, `SERVICE` `Auth` payloads.
+
+<!-- owlmeans:agent-guidance:start -->
+## Agent guidance
+
+This package ships embedded Claude Code skills and GitHub Copilot instructions under
+`agent-meta/`. After installing your `@owlmeans/*` packages, run the OwlMeans
+agent-skills installer to place them into your project's native locations
+(`.claude/skills/` and `.github/instructions/`):
+
+```sh
+npx @owlmeans/agent-skills
+```
+
+The embedded files are version-matched to this package release. Do not edit them
+directly — they are regenerated on each publish. To contribute guidance edits,
+open a PR against the source monorepo.
+<!-- owlmeans:agent-guidance:end -->

package/agent-meta/instructions/testing-auth-unit.instructions.md

@@ -0,0 +1,17 @@
+---
+applyTo: "**/*.test.ts, **/*.spec.ts, **/*.ts"
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# Category B — Auth Unit Tests
+
+- Tests in `<your-package>/tests/*.spec.ts`. Use `bun:test`.
+- The **only** mocks allowed: `@owlmeans/test-auth` helpers (`makeFixtureKeyPair`, `makeMemoryTrustedResource`, `makeMockGuard`, `withAuth`, `signMockEnvelope`, `makeBearer`).
+- Never roll a new auth mock in a per-package `tests/`. Add it to `@owlmeans/test-auth` and update its skill instead.
+- Use deterministic seeds: `makeFixtureKeyPair('alice')` keeps signatures stable.
+- Cover `.claude/skills/<pkg>/SKILL.md` and `README.md` cases first.
+- Max 3-4 tests per method/function.
+- Don't test utils, types, or context plumbing.
+- Per-package `package.json` script: `"test": "bun test ./tests"`.
+
+For the protocol reference (Ed25519 path, OIDC path, types, errors, mocking points), see `.claude/skills/auth-protocol/SKILL.md`. For helper specifics, see `.claude/skills/testing-auth-unit/SKILL.md`.

package/agent-meta/manifest.json

@@ -0,0 +1,23 @@
+{
+  "schemaVersion": 1,
+  "package": "@owlmeans/test-auth",
+  "version": "0.1.8",
+  "generatedAt": "2026-06-11T16:30:27.163Z",
+  "canonicalRepo": "https://github.com/owlmeans/common",
+  "entries": [
+    {
+      "kind": "skill",
+      "name": "testing-auth-unit",
+      "category": "package-specific",
+      "file": "skills/testing-auth-unit/SKILL.md",
+      "canonicalPath": ".claude/skills/testing-auth-unit/SKILL.md"
+    },
+    {
+      "kind": "instruction",
+      "name": "testing-auth-unit",
+      "category": "package-specific",
+      "file": "instructions/testing-auth-unit.instructions.md",
+      "canonicalPath": ".github/instructions/testing-auth-unit.instructions.md"
+    }
+  ]
+}

package/agent-meta/skills/testing-auth-unit/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: testing-auth-unit
+description: Category-B unit tests for OwlMeans Common — auth/authz packages where the test substitutes a fake authenticated identity via @owlmeans/test-auth. Auto-invoked when writing tests in auth, auth-common, basic-keys, basic-envelope, did, client-auth, client-did, server-auth, oidc, server-oidc-*, web-oidc-*, wled, client-payment.
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# Auth Unit Tests — Category B
+
+Category B applies to the auth/authz packages: `auth`, `auth-common`, `basic-keys`, `basic-envelope`, `did`, `client-auth`, `client-did`, `server-auth`, `oidc`, `server-oidc-rp`, `server-oidc-provider`, `web-oidc-rp`, `web-oidc-provider`, `wled`, `client-payment`. These tests run under `bun test` (no Playwright even when there are React bits) and are the **only** place mocks are allowed — and only for authentication/authorization, via `@owlmeans/test-auth`.
+
+For background on the protocol you're mocking, read the `auth-protocol` skill.
+
+## Helpers from `@owlmeans/test-auth`
+
+| Helper | Purpose |
+|---|---|
+| `makeFixtureKeyPair(seed?)` | Deterministic Ed25519 `KeyPairModel`. Same seed → same keys. |
+| `makeMemoryTrustedResource(records?)` | `Resource<TrustedRecord>` that satisfies `trust()` lookups. |
+| `makeMockGuard({ alias?, auth?, allow? })` | `GuardService` resolving to a chosen `Auth`. |
+| `withAuth(ctx, auth)` | Registers a mock guard on `ctx` that resolves to `auth`. |
+| `signMockEnvelope(msg, type, kind?, kp?)` | Wraps `makeEnvelopeModel` with a fixture keypair. |
+| `makeBearer(auth, kp?)` | Produces an `ED25519-BASIC-TOKEN <encoded>` header. |
+| `SUPERUSER`, `USER`, `SERVICE` | Canonical `Auth` payload fixtures. |
+
+## `tests/context.ts` pattern
+
+```ts
+import { AppType, Layer, makeBasicContext } from '@owlmeans/context'
+import { makeMemoryTrustedResource, withAuth, USER } from '@owlmeans/test-auth'
+
+export const makeTestCtx = () => {
+  const ctx = makeBasicContext({
+    ready: false, service: '<pkg>-tests', layer: Layer.Service, type: AppType.Backend,
+  })
+  ctx.registerResource(makeMemoryTrustedResource([
+    { id: 'svc', name: 'svc', credential: '<fixture-pubkey>' },
+  ]))
+  withAuth(ctx, USER)        // register a mock guard resolving to USER
+  return ctx
+}
+```
+
+The trusted resource, mock guard, and any fixture keys are the **only** mocks allowed. Everything else (the service under test, sibling packages it depends on) is the real thing.
+
+## Spec shape
+
+```ts
+import { describe, expect, test } from 'bun:test'
+import { makeFixtureKeyPair } from '@owlmeans/test-auth'
+import { packAuthCredentials, unpackAuthCredentials } from '@owlmeans/basic-keys'
+
+const key = makeFixtureKeyPair('alice')
+
+describe('@owlmeans/basic-keys — packAuthCredentials', () => {
+  test('round-trips a signed credential', async () => {
+    const signed = await packAuthCredentials(/* … */, undefined, key)
+    const result = await unpackAuthCredentials(signed, key)
+    expect(result.isValid).toBe(true)
+  })
+})
+```
+
+## Rules
+
+- **Mocks only for auth/authz.** No mocks for databases, network, or any sibling package. If you need one, move the spec to category C and write an integration test.
+- **Don't replicate `@owlmeans/test-auth` helpers in your package.** If you need a new mocking primitive (e.g. an OIDC userinfo endpoint stub), add it to `@owlmeans/test-auth` and its skill — never to a per-package `tests/`.
+- **Use deterministic seeds.** `makeFixtureKeyPair('<seed>')` keeps signatures stable run-to-run; random keypairs break snapshot-style assertions.
+- **Cover SKILL.md cases first.** The package's `.claude/skills/<pkg>/SKILL.md` documents the consumer-facing surface — that's the test priority order.
+- **Max 3-4 tests per method/function.** Same as category A.
+- **Don't test types or utils.**
+
+## When you actually want OIDC end-to-end
+
+The current `@owlmeans/test-auth` does not ship a fake JWKS server. Use the real `makeOidcGuard` against the in-memory trusted resource and a fixture keypair. If a future test needs a hostable IdP fake, add it to `@owlmeans/test-auth` and document it here — don't bolt it on per package.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/test-auth",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -21,14 +21,14 @@
     }
   },
   "dependencies": {
-    "@owlmeans/auth": "^0.1.7",
-    "@owlmeans/auth-common": "^0.1.7",
-    "@owlmeans/basic-envelope": "^0.1.7",
-    "@owlmeans/basic-keys": "^0.1.7",
-    "@owlmeans/context": "^0.1.7",
-    "@owlmeans/entrypoint": "^0.1.7",
-    "@owlmeans/resource": "^0.1.7",
-    "@owlmeans/test": "^0.1.7"
+    "@owlmeans/auth": "^0.1.8",
+    "@owlmeans/auth-common": "^0.1.8",
+    "@owlmeans/basic-envelope": "^0.1.8",
+    "@owlmeans/basic-keys": "^0.1.8",
+    "@owlmeans/context": "^0.1.8",
+    "@owlmeans/entrypoint": "^0.1.8",
+    "@owlmeans/resource": "^0.1.8",
+    "@owlmeans/test": "^0.1.8"
   },
   "devDependencies": {
     "@owlmeans/dep-config": "workspace:*",