@ketecode/loom 0.0.0-stage → 0.1.0

package/skills/architecture-decision-records/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: architecture-decision-records
+description: Writes and maintains Architecture Decision Records (ADRs), deciding whether a choice deserves one, filling a short template (Nygard sections plus options considered) with context, the options weighed, the decision and its consequences, numbering and storing it next to the code, and superseding old records instead of rewriting them. Use when the user wants to record or document a technical decision, start an ADR log in a repo, or update the status of an earlier decision.
+license: MIT
+compatibility: Any Agent Skills host. Writes Markdown files; git is optional.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: docs
+  kete-loom/risk: writes-files
+  kete-loom/owner: "Kete-org"
+---
+
+# Architecture decision records
+
+An ADR captures one decision, the reason for it, and what it costs, so a future reader can tell whether the reason still holds. It is short, dated and never silently edited.
+
+## Does this need an ADR?
+
+Write one when the decision is **hard to reverse, affects more than one module or team, or someone will later ask "why did we do it this way?"** Examples: choosing a database, message broker, auth provider, framework, API style, deployment model; adopting or dropping an architectural pattern; a deliberate trade-off against a stated quality (accepting eventual consistency, skipping multi-region).
+
+Don't write one for: library patch upgrades, naming, formatting, decisions fully captured by a ticket, or anything trivially reversible. Say so and stop.
+
+## Steps
+
+1. **Find the log.** Search the repo for an existing ADR directory: `docs/adr/`, `doc/adr/` (the adr-tools default), `docs/decisions/`, `doc/architecture/decisions/`, `adr/`, or an `.adr-dir` file (adr-tools stores the chosen directory there). Use it and its template and numbering exactly. If none exists, propose `docs/adr/` and create `0001-record-architecture-decisions.md` first, then the user's ADR.
+2. **Gather the facts.** You need: the problem and forces (constraints, requirements, deadlines), at least two real options (including "do nothing" when plausible), the chosen option, and who decided. **Stop and ask the user** for anything missing. Never invent the reasons, the alternatives considered or the people involved.
+3. **Number and name.** Next free four-digit number, kebab-case title stating the decision: `0007-use-postgres-for-event-store.md`. Numbers are never reused.
+4. **Write it** with the template below. Keep it to one or two screens. Link to longer analysis rather than pasting it.
+5. **Set the status** (see lifecycle). New records start as `Proposed` unless the user says the decision is made.
+6. **Supersede, don't rewrite.** When a decision changes, write a new ADR, set the old one's status to `Superseded by ADR-00NN` and add `Supersedes ADR-00MM` to the new one. Only typo fixes and status lines change in accepted ADRs.
+7. **Index.** If the log has a README or index listing ADRs, add the new line.
+
+## Template
+
+```markdown
+# ADR-0007: Use Postgres for the event store
+
+- Status: Proposed | Accepted | Rejected | Deprecated | Superseded by ADR-00NN
+- Date: 2026-03-01
+- Deciders: names or roles
+- Supersedes: ADR-00MM (if any)
+
+## Context
+
+What problem forces a decision now. Constraints, requirements, quality
+attributes that matter (cost, latency, team skills, compliance). Facts, not
+the conclusion.
+
+## Options considered
+
+1. **Postgres with an append-only events table**: pros, cons.
+2. **EventStoreDB**: pros, cons.
+3. **Kafka as the system of record**: pros, cons.
+
+## Decision
+
+We will use option 1 because <the deciding reasons, tied to the context>.
+
+## Consequences
+
+- Positive: what gets easier.
+- Negative: what gets harder or what we accept (the trade-off, stated plainly).
+- Follow-ups: work this creates, and the signal that would make us revisit it.
+```
+
+## Status lifecycle
+
+```
+Proposed ──▶ Accepted ──▶ Deprecated
+    │            └──────▶ Superseded by ADR-NNNN
+    └──▶ Rejected
+```
+
+- `Proposed`: under discussion, usually in a pull request.
+- `Accepted`: merged and in force.
+- `Rejected`: kept on purpose, so the option isn't re-litigated without new facts.
+- `Deprecated`: no longer relevant (the system it governed is gone).
+- `Superseded`: replaced by a newer ADR, linked both ways.
+
+## Where to store them
+
+- In the repo of the code they govern, as Markdown, reviewed in pull requests like code. Cross-cutting decisions go in a shared architecture repo, linked from each affected repo.
+- If the team uses a tool (adr-tools, Log4brains), follow its file layout and commands instead of hand-numbering.
+
+## Writing rules
+
+- One decision per ADR. If you need "and" in the title, split it.
+- The Consequences section must include at least one negative. A decision with no cost wasn't a decision.
+- Write the context so a new hire understands it without the meeting.
+- Dates are absolute (`2026-03-01`), never "last sprint".
+
+## Report back
+
+```
+ADR: path/to/NNNN-title.md (status)
+Updated: older ADRs whose status changed, index file
+Missing facts: anything you left as a question for the user
+```

package/skills/architecture-decision-records/evals/triggers.json

@@ -0,0 +1,17 @@
+{
+  "should_trigger": [
+    "Write an ADR for our decision to move from RabbitMQ to Kafka",
+    "We agreed in the meeting to use Keycloak for auth, can you document that decision in the repo?",
+    "Set up an architecture decision log in this repo with the first record",
+    "ADR 0004 is outdated since we switched to DynamoDB, mark it superseded and write the new one",
+    "Record why we chose server-side rendering over a SPA so future devs understand it"
+  ],
+  "should_not_trigger": [
+    "Should we use RabbitMQ or Kafka for order events? Weigh the options and recommend one",
+    "Write a README section explaining how to run the project locally",
+    "Draft the changelog and release notes for version 2.3.0",
+    "Design the pagination and versioning scheme for the public API",
+    "Write a commit message for these staged changes",
+    "Turn this feature request into a step-by-step implementation plan"
+  ]
+}

package/skills/article-writing/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: article-writing
+description: Long-form article and blog post writing, from choosing a sharp angle and outlining, through gathering evidence and drafting in plain prose, to a structured editing pass and a final headline, summary and meta description. Use when someone wants a blog post, essay, opinion piece, case study, newsletter feature or company announcement of roughly 800 words or more written, restructured or edited for clarity.
+license: MIT
+compatibility: Any Agent Skills host. Web access helps when the article needs facts checked; otherwise works from the user's material.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: business
+  kete-loom/risk: read-only
+  kete-loom/owner: "Kete-org"
+---
+
+# Article writing
+
+Write a piece a busy reader finishes and remembers. One reader, one point, evidence for it, plain words.
+
+## 0. Brief
+
+Ask for what is missing, in one message:
+
+1. **Reader**: who they are and what they already know.
+2. **Purpose**: what the reader should think, feel or do afterwards.
+3. **Format and length**: blog post, essay, case study, announcement; target word count.
+4. **Where it runs**: company blog, newsletter, publication (and their style rules).
+5. **Material**: notes, data, interviews, links, drafts, and the author's own experience.
+6. **Voice**: a brand voice guide if one exists (apply it; the `brand-voice` skill covers defining one).
+
+If the user says "just write it", state your assumptions in two lines at the top of the draft and proceed.
+
+## 1. Angle
+
+- Write the **one-sentence point** of the article. If you cannot, the topic is too broad; offer two or three sharper angles and let the user pick.
+- Good angles are specific and arguable: "Why we stopped offering a free plan" beats "Thoughts on pricing".
+- Check the angle against the reader: why would they care now?
+
+## 2. Outline
+
+Before drafting, show the user a short outline:
+
+```
+Working headline:
+Point (one sentence):
+Opening: <the hook: a scene, a surprising fact, a problem the reader has>
+Section 1: <claim>  - evidence:
+Section 2: <claim>  - evidence:
+Section 3: <claim>  - evidence:
+Close: <what to do or think next>
+```
+
+Three to five sections is typical. Each section makes one claim that supports the point. For long or high-stakes pieces, **stop and get agreement** on the outline before drafting.
+
+## 3. Evidence
+
+- Back each claim with something concrete: data, an example, a quote, a story from the author's experience, a demo or code.
+- Attribute facts and link to the source. Prefer primary sources.
+- If a fact cannot be verified, cut it or flag it to the user as `[CHECK: ...]`. Never invent statistics, quotes, studies or customer stories.
+- Mark the author's opinions as opinions.
+
+## 4. Draft
+
+- Open with the hook and state the point within the first few paragraphs. No throat-clearing ("In today's fast-paced world...").
+- One idea per paragraph. Topic sentence first.
+- Short, common words. Active voice. Concrete nouns and verbs.
+- Subheadings that say something ("Free users cost us 30% of support time"), not labels ("Background").
+- Explain jargon the reader may not know, or remove it.
+- Use lists for steps or parallel items, prose for argument.
+- End with a close that pays off the opening: a takeaway, a next step or a call to action. Do not just summarise.
+
+## 5. Editing pass
+
+Go through the draft in this order, one pass per item:
+
+1. **Structure**: does every section support the point? Cut or move what doesn't.
+2. **Opening**: would the reader keep going after three sentences?
+3. **Cut**: remove repetition, filler (very, really, just, actually), hedges that add nothing, and sentences that restate the previous one. Aim to cut 10-20%.
+4. **Clarity**: split sentences over about 25 words; replace abstractions with examples.
+5. **Accuracy**: every number, name, quote and link checked against its source.
+6. **Consistency**: terms, capitalisation, spelling variant (US or UK) and voice.
+7. **Read aloud** test: flag anything awkward.
+
+## 6. Headline, summary and metadata
+
+- Offer three to five headline options: specific, honest, ideally with the benefit or the surprise. No clickbait the article does not deliver.
+- A one- or two-sentence summary (standfirst or dek).
+- A meta description for the web, and a suggested URL slug. Google sets no fixed length and truncates by display width, so keep the key point in the first 120 characters or so; about 150-160 characters is a common convention, not a rule.
+- If the piece targets search, use the phrase readers would search for in the headline or first paragraph naturally; do not stuff keywords.
+
+## Rules
+
+- Never fabricate facts, quotes, sources or anecdotes, and never present the author as having done something they did not tell you about.
+- Do not copy text from sources; quote briefly with attribution or paraphrase.
+- Keep the author's voice when editing their draft; fix problems, do not rewrite their personality away.
+- For technical docs (API references, READMEs, how-to guides inside a product) use the `technical-writing` skill instead.
+
+## Output
+
+```
+# <Headline>
+<Summary / standfirst>
+
+<Article body>
+
+---
+Headline options: 1. ... 2. ... 3. ...
+Meta description: <...>   Slug: <...>
+Word count: <n>
+To check: <list of [CHECK] items and sources to confirm>
+```

package/skills/article-writing/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Write a 1500-word blog post on why we rebuilt our checkout around mobile money",
+    "Here's my messy draft about remote hiring. Can you restructure and tighten it into a proper article?",
+    "I want an opinion piece arguing that small startups should skip microservices. Give me an angle and outline first.",
+    "Turn these interview notes into a customer case study for our blog",
+    "Give me a few headline options and a meta description for this finished essay"
+  ],
+  "should_not_trigger": [
+    "Write the README and API reference for our Node SDK",
+    "Create a style guide describing our brand personality with do and don't examples",
+    "Write a short commit message for these staged changes",
+    "Plan the content calendar and paid budget for next quarter's campaign",
+    "Audit our blog for crawl and indexing problems"
+  ]
+}

package/skills/aspnet-core-patterns/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: aspnet-core-patterns
+description: ASP.NET Core web API and app hosting decisions - choosing minimal APIs or controllers, ordering the middleware pipeline, picking singleton, scoped or transient lifetimes without captive dependencies, binding and validating settings with the options pattern, request validation, JWT or cookie authentication with policy-based authorization, RFC 7807 problem details for errors, and liveness and readiness health checks. Use when building or reviewing an ASP.NET Core service, wiring Program.cs, debugging a 401, 500 or middleware-order bug, or adding auth, validation or health endpoints to a .NET web app.
+license: MIT
+compatibility: Any Agent Skills host. Needs the .NET SDK (dotnet CLI). Written for .NET 8 and later; .NET 10-only features are marked.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "dotnet"
+  kete-loom/owner: "Kete-org"
+---
+
+# ASP.NET Core patterns
+
+Wire the host so requests flow through the right middleware, services live as long as they should, and every error comes back in one shape. For C# language style follow `csharp-patterns`; for xUnit and `WebApplicationFactory` tests follow `csharp-testing`; for the data layer follow `ef-core-patterns`.
+
+## 0. Before you change anything
+
+1. Read the `.csproj` `TargetFramework` and `Program.cs`. Match the project's style (minimal APIs or controllers, `TypedResults` or `IActionResult`).
+2. Run `dotnet build` and `dotnet test`. If either fails before you start, **stop and tell the user**.
+
+## 1. Minimal APIs or controllers
+
+| Choose | When |
+|---|---|
+| Minimal APIs | New services, small to medium APIs, you want `TypedResults` and route groups |
+| Controllers | The project already uses them, or you need filters, model binding conventions or OData-style features built around `ControllerBase` |
+
+Don't mix both in one feature area. For minimal APIs:
+
+- Group routes: `var orders = app.MapGroup("/orders").RequireAuthorization();`
+- Keep handlers short; move them into static methods or a class per feature (`OrderEndpoints.Map(app)`), not one giant `Program.cs`.
+- Return `TypedResults` with a `Results<Ok<OrderDto>, NotFound>` return type so OpenAPI and tests see every outcome.
+- Accept `CancellationToken` in handlers and pass it to every async call.
+
+## 2. Middleware order
+
+Order matters; the request passes top to bottom and the response bottom to top. The usual order:
+
+```csharp
+app.UseExceptionHandler();           // first, so it catches everything below
+if (!app.Environment.IsDevelopment()) app.UseHsts();
+app.UseHttpsRedirection();
+app.UseStaticFiles();                // or app.MapStaticAssets() on .NET 9+
+app.UseRouting();                    // implicit if omitted; explicit when order matters
+app.UseCors();                       // after routing, before auth
+app.UseAuthentication();
+app.UseAuthorization();
+app.UseRateLimiter();                // after routing when using endpoint-specific policies
+// custom middleware that needs the user goes here
+app.MapControllers();                // or Map... endpoints
+```
+
+Symptoms of a wrong order: CORS preflight failing with 401 (auth before CORS), `[Authorize]` ignored or `User` empty (auth after endpoints, or authentication missing), errors returning HTML or empty 500s (exception handler not first).
+
+## 3. DI lifetimes
+
+| Lifetime | Use for | Never |
+|---|---|---|
+| Singleton | Stateless, thread-safe services, caches, `HttpClient` handlers via factory | Inject a scoped service (captive dependency) |
+| Scoped | One per request: `DbContext`, unit of work, current-user accessors | Resolve from the root provider or a singleton |
+| Transient | Lightweight, stateless helpers | Hold expensive resources |
+
+- Keep `ValidateScopes` and `ValidateOnBuild` on (default in Development) so captive dependencies fail at startup.
+- `BackgroundService` and other singletons that need scoped services create a scope: `using var scope = scopeFactory.CreateScope();`.
+- HTTP clients: `builder.Services.AddHttpClient<PaymentsClient>(c => c.BaseAddress = ...)`. Never `new HttpClient()` per call.
+- Prefer constructor injection. Don't inject `IServiceProvider` to resolve things manually.
+
+## 4. Options pattern
+
+```csharp
+builder.Services.AddOptions<SmtpOptions>()
+    .Bind(builder.Configuration.GetSection("Smtp"))
+    .ValidateDataAnnotations()
+    .ValidateOnStart();
+```
+
+- `IOptions<T>`: read once, singleton-safe. `IOptionsSnapshot<T>`: re-read per request (scoped). `IOptionsMonitor<T>`: change notifications, singleton-safe.
+- `ValidateOnStart()` makes a missing setting fail at boot, not on the first request.
+- Secrets: user-secrets (`dotnet user-secrets set "Smtp:Password" ...`) in development, environment variables or a vault provider in production. Never in `appsettings.json` committed to git.
+- Environment variable form of `Smtp:Password` is `Smtp__Password`.
+
+## 5. Validation
+
+- Controllers with `[ApiController]` return a 400 `ValidationProblemDetails` automatically when DataAnnotations fail.
+- Minimal APIs on .NET 10: `builder.Services.AddValidation();` validates DataAnnotations on query, header and body parameters and returns 400 problem details; opt out per endpoint with `.DisableValidation()`.
+- Minimal APIs before .NET 10: validate in an endpoint filter or with the FluentValidation library the project already uses, and return `TypedResults.ValidationProblem(errors)`.
+- Validate business rules (stock, ownership, state transitions) in the domain or handler, not only with attributes.
+
+## 6. Authentication and authorization
+
+```csharp
+builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
+    .AddJwtBearer(o => { o.Authority = ...; o.Audience = ...; });
+builder.Services.AddAuthorizationBuilder()
+    .AddPolicy("orders:write", p => p.RequireClaim("scope", "orders:write"))
+    .SetFallbackPolicy(new AuthorizationPolicyBuilder().RequireAuthenticatedUser().Build());
+```
+
+- A fallback policy makes endpoints secure by default; mark public ones with `.AllowAnonymous()` / `[AllowAnonymous]`.
+- Use named policies (`.RequireAuthorization("orders:write")`), not role strings scattered across handlers.
+- Resource checks (does this user own order 42?) use `IAuthorizationService.AuthorizeAsync(User, order, "OwnerPolicy")` or a query scoped to the user. Return 404 when revealing existence would leak data.
+- Cookie auth for browser apps needs antiforgery on form posts; JWT APIs don't use cookies.
+- Never disable `ValidateIssuer`, `ValidateAudience` or `ValidateLifetime` to "make it work".
+
+## 7. Problem details for every error
+
+```csharp
+builder.Services.AddProblemDetails();
+app.UseExceptionHandler();
+app.UseStatusCodePages();
+```
+
+- `UseExceptionHandler()` with no arguments throws at startup unless `AddProblemDetails()` or an `IExceptionHandler` is registered.
+- Unhandled exceptions become `application/problem+json` 500s without stack traces outside Development.
+- Expected failures return `TypedResults.Problem(...)` / `ValidationProblem(...)` or `Problem()` in controllers with a stable `type` and `title`.
+- For custom mapping (domain exception to 409), implement `IExceptionHandler` and register with `AddExceptionHandler<T>()`.
+- Log the exception once, in the handler, with the trace id; return the trace id, not the message, to the client.
+
+## 8. Health checks
+
+```csharp
+builder.Services.AddHealthChecks()
+    .AddCheck("self", () => HealthCheckResult.Healthy(), tags: ["live"])
+    .AddDbContextCheck<AppDbContext>(tags: ["ready"]);   // Microsoft.Extensions.Diagnostics.HealthChecks.EntityFrameworkCore
+app.MapHealthChecks("/health/live",  new() { Predicate = r => r.Tags.Contains("live") });
+app.MapHealthChecks("/health/ready", new() { Predicate = r => r.Tags.Contains("ready") });
+```
+
+- Liveness checks only the process; readiness checks dependencies. A database outage must not make the orchestrator restart every pod.
+- A fallback authorization policy also applies to `MapHealthChecks`, so probes start getting 401. Add `.AllowAnonymous()` to the health endpoints (or restrict them by host/port with `RequireHost`), and keep them cheap and free of secrets.
+
+## Stop and ask the user
+
+- Before changing the authentication scheme, token validation parameters or the fallback policy.
+- Before changing CORS to allow any origin with credentials.
+- Before moving between minimal APIs and controllers for existing endpoints.
+
+## Never
+
+- Never put secrets in `appsettings*.json` in source control.
+- Never `.Result` or `.Wait()` on tasks in request code.
+- Never return exception messages or stack traces to clients in production.
+- Never register `DbContext` as a singleton.
+
+## Finish
+
+Run `dotnet build` with warnings visible and `dotnet test`. Report: files changed, pipeline order changes, new services and their lifetimes, and endpoints whose auth changed.

package/skills/aspnet-core-patterns/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "CORS preflight returns 401 in my ASP.NET Core API, is my middleware order wrong?",
+    "Should this new .NET 8 service use minimal APIs or controllers, and how do I group the routes?",
+    "Bind the Smtp section of appsettings to an options class in ASP.NET Core and fail at startup if it's missing",
+    "Make every unhandled exception in our ASP.NET Core API return RFC 7807 problem details",
+    "Add liveness and readiness health check endpoints to the ASP.NET Core orders service"
+  ],
+  "should_not_trigger": [
+    "Turn on nullable reference types across this C# class library and fix the warnings",
+    "Write an xUnit test with WebApplicationFactory for the orders endpoint",
+    "My EF Core query throws 'could not be translated', how do I rewrite it?",
+    "Add a dotnet ef migration for the new Invoice table",
+    "Write a Kubernetes deployment manifest with readiness probes for this container"
+  ]
+}

package/skills/auth-patterns/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: auth-patterns
+description: Implementing login, sessions and access control correctly on the server - password hashing with Argon2id or bcrypt, cookie sessions versus JWT access tokens, OAuth 2.1 and OpenID Connect authorization code flow with PKCE, TOTP and passkey MFA, role- and attribute-based permission checks, safe token storage in browsers and mobile apps, and password reset and account recovery. Use when building or changing sign-up, sign-in, logout, social login or SSO, adding roles and permissions, deciding where to keep tokens, wiring up an identity provider, or designing a forgot-password flow.
+license: MIT
+compatibility: Any Agent Skills host. Framework-neutral; examples name common libraries but the rules apply to any backend language.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: security
+  kete-loom/risk: writes-files
+  kete-loom/owner: "Kete-org"
+---
+
+# Authentication and authorization patterns
+
+Build auth that holds up when the client is hostile. This skill is for writing or changing auth code. To audit existing code for flaws, use the security-review skill or the security-reviewer agent.
+
+## 0. Decide before writing code
+
+1. **Prefer not to build it.** If the framework ships auth (Django auth, Rails 8's authentication generator or Devise, ASP.NET Core Identity, Laravel Fortify/Sanctum, Spring Security) or the project already uses a managed identity provider, use that. Hand-rolled crypto, token formats or OAuth servers are a **stop and ask** point.
+2. Identify the client types: server-rendered web, SPA, mobile/desktop app, machine-to-machine. They need different token handling (section 3).
+3. Find the existing pattern: search the codebase for the session middleware, the current-user helper and how routes are protected. Extend it; don't add a second auth system.
+
+## 1. Passwords
+
+- Hash with **Argon2id** (minimum m=19 MiB, t=2, p=1). If unavailable: scrypt (N=2^17, r=8, p=1), bcrypt (cost 10 or more; it ignores input past **72 bytes**, so cap length or pre-handle long input), or PBKDF2-HMAC-SHA256 at 600,000 iterations where FIPS is required. These are the OWASP Password Storage Cheat Sheet minimums; raise them as hardware allows.
+- Use the library's own `hash` and `verify`; never compare hashes with `==`. Store the full encoded string (it carries the salt and parameters) and rehash on login when parameters change.
+- Policy (NIST SP 800-63B style): favour length over composition rules, allow at least 64 characters and any Unicode, reject passwords found in a breached-password list, no forced periodic rotation, no password hints or security questions.
+- Login responses and timing must not reveal whether the account exists: same message for unknown user and wrong password, and run a dummy verify for unknown users.
+- Rate-limit by account and by IP, with backoff, not permanent lockout (lockout is itself a denial-of-service tool).
+
+## 2. Sessions vs tokens
+
+Default for a browser app on your own domain: **server-side session with an opaque ID in a cookie.** It is revocable, small and safe from script access.
+
+| Use | When |
+|---|---|
+| Cookie session (opaque ID, server store) | Web app and API on the same site, including SPAs served from your domain or through a backend-for-frontend |
+| Short-lived JWT access token + refresh token | APIs called by mobile apps, third parties or many services that must verify without a session store |
+| Client credentials / workload identity | Machine to machine; no user |
+
+Session cookie flags: `HttpOnly; Secure; SameSite=Lax` (or `Strict`), `Path=/`, and the `__Host-` name prefix so it can't be set by a subdomain. On login and on privilege change, **issue a new session ID** (prevents fixation). Enforce idle and absolute timeouts. Logout deletes the server-side session, not just the cookie. Cookie-authenticated state-changing requests need CSRF protection (framework token, or `SameSite` plus an `Origin` check).
+
+JWT rules, if you use them:
+
+1. Verify the signature with an **allow-list of algorithms** fixed in config; reject `none` and never take the algorithm or key from the token header.
+2. Check `iss`, `aud`, `exp` and `nbf` on every request, with a small clock skew.
+3. Access tokens live minutes, not days. Put an ID and roles in them, never secrets or personal data (JWTs are readable by anyone).
+4. Refresh tokens are opaque, stored hashed server-side, **rotated on every use**, and a reused old one revokes the whole family.
+5. You can't revoke a JWT before it expires without a deny-list; keep lifetimes short for that reason.
+
+## 3. Token storage by client
+
+- **Server-rendered or same-site SPA**: HttpOnly cookie. Do not put tokens in `localStorage` or `sessionStorage`; any XSS can read them.
+- **SPA calling third-party APIs**: prefer a backend-for-frontend that holds tokens server-side and gives the browser only a session cookie. If tokens must live in the browser, keep them in memory and use refresh token rotation.
+- **Mobile**: iOS Keychain, Android Keystore-backed storage. Never in plain shared preferences, files or logs.
+- **Servers and CI**: secret manager or environment, never in the repo.
+
+## 4. OAuth 2.1 and OpenID Connect
+
+Use a maintained client library and the provider's discovery document (`/.well-known/openid-configuration`). The flow for every user-facing client is **authorization code with PKCE (`S256`)**, including confidential server-side clients. Never implement the implicit grant or the resource owner password grant: RFC 9700 (OAuth 2.0 Security BCP) says the password grant MUST NOT be used and clients SHOULD NOT use the implicit grant, and the OAuth 2.1 draft removes both.
+
+Non-negotiable checks: exact redirect URI matching, a random `state` bound to the user's session, `nonce` in OIDC, ID token signature and claims validation, and linking the account by the provider's `sub` + `iss` (not by email alone unless the provider asserts `email_verified` and you accept that risk). Full flow, validation list and pitfalls: `references/oauth-oidc.md`.
+
+## 5. MFA
+
+- Offer **passkeys / WebAuthn** where possible; they are phishing-resistant. Use a maintained WebAuthn server library and verify origin, RP ID and the signature counter it reports.
+- **TOTP** (RFC 6238): 30-second step, accept at most one step of drift, reject a code already used in its window, store the shared secret encrypted, rate-limit attempts.
+- SMS and email codes are weaker fallbacks; never the only second factor for admin accounts.
+- **Recovery codes**: generated once, shown once, stored hashed, single use.
+- Require re-authentication (step-up) before changing email, password, MFA settings or payout details.
+
+## 6. Authorization
+
+1. **Deny by default.** Every route, resolver, RPC and background job that acts for a user checks permission on the server. Hidden UI is not a control.
+2. Check **the action on this resource**, not just the role: load the object, then `can(user, "update", invoice)`. Scope queries by owner or tenant (`WHERE tenant_id = :current_tenant`) so another tenant's ID returns nothing (prevents IDOR).
+3. **RBAC** for coarse capability (admin, member, viewer); **ABAC or relationship rules** for ownership, tenant, state ("only the author can edit a draft"). Put the rules in one policy module or library (Pundit, CASL, django-rules, Spring `@PreAuthorize`, OPA/Cedar), not scattered `if` statements.
+4. Never trust client-sent roles, user IDs, tenant IDs or prices; derive them from the session.
+5. Write tests for the negative cases: another user's resource, a lower role, a deactivated account, an expired session.
+
+## 7. Account recovery
+
+- Reset tokens: at least 128 bits from a CSPRNG, **stored hashed**, single use, expiring in minutes to an hour, invalidated when a new one is issued.
+- Same response whether or not the email exists. Send the link only to the address already on file.
+- On reset: invalidate all existing sessions and refresh tokens, notify the user, and do not log them in silently if MFA is enabled (still require the second factor).
+- Email change: confirm via the new address and notify the old one.
+- Support-driven recovery needs a documented identity check; it is the usual way accounts get taken over.
+
+## 8. Logging
+
+Log sign-in success and failure, MFA changes, password resets, role changes and token revocations with user ID, IP and time. Never log passwords, tokens, reset links, session IDs or TOTP secrets.
+
+## Never
+
+- Never store passwords reversibly or with fast hashes (MD5, SHA-1, SHA-256 alone).
+- Never invent your own token format, signature scheme or OAuth server.
+- Never put tokens in URLs, `localStorage`, logs or analytics.
+- Never authorize from data the client sends.
+- Never weaken an existing control (shorter hash cost, longer token life, removed CSRF check) without telling the user.
+
+## Before you finish
+
+- Tests cover: wrong password, unknown user, expired and tampered token, reused refresh token, another user's resource, missing role, CSRF on a cookie-authenticated mutation, reset token reuse.
+- Run the project's tests and linters.
+- Summarise for the user: what flow you built, where secrets are read from, token lifetimes, and anything left for them to configure at the identity provider.

package/skills/auth-patterns/evals/triggers.json

@@ -0,0 +1,17 @@
+{
+  "should_trigger": [
+    "Add Google sign-in to our Express app using OIDC with PKCE",
+    "Should I use JWTs or server sessions for my SPA's login?",
+    "How should we hash user passwords? We're on bcrypt cost 8 right now",
+    "Implement a forgot-password flow with reset links that expire",
+    "Add roles and per-resource permissions so members can only edit their own team's projects",
+    "Where should my React Native app store the access and refresh tokens?"
+  ],
+  "should_not_trigger": [
+    "Find the vulnerabilities in our existing login handler code",
+    "Threat model our new SSO integration with the customer's identity provider",
+    "Add a password strength meter to the signup form UI",
+    "Design REST endpoints and error formats for our public orders API",
+    "Write a HIPAA access control policy document for our clinic records system"
+  ]
+}

package/skills/auth-patterns/references/oauth-oidc.md

@@ -0,0 +1,64 @@
+# OAuth 2.1 / OpenID Connect: authorization code flow with PKCE
+
+Read this when wiring up social login, SSO or any OAuth client. Status note: OAuth 2.1 is still an IETF Internet-Draft (draft-ietf-oauth-v2-1) at the time of writing; its rules consolidate RFC 6749, RFC 7636 (PKCE) and RFC 9700 (OAuth 2.0 Security Best Current Practice, January 2025). Follow RFC 9700 where your provider is OAuth 2.0.
+
+## Flow
+
+```
+1. Client creates:
+   code_verifier  = 43-128 chars from a CSPRNG (base64url)
+   code_challenge = BASE64URL(SHA256(code_verifier)), method S256
+   state          = random, stored in the user's session (CSRF protection)
+   nonce          = random, stored in the session (OIDC replay protection)
+
+2. Redirect the browser to the authorization endpoint:
+   GET /authorize?response_type=code&client_id=...&redirect_uri=<exact registered URI>
+       &scope=openid%20profile%20email&state=...&nonce=...
+       &code_challenge=...&code_challenge_method=S256
+
+3. Provider redirects back: GET <redirect_uri>?code=...&state=...
+   - Reject if state is missing or differs from the session value. Delete it after use.
+   - If the provider supports it, check the `iss` response parameter (RFC 9207) matches the expected issuer (mix-up defence).
+
+4. Server exchanges the code (back channel):
+   POST /token  grant_type=authorization_code&code=...&redirect_uri=...&code_verifier=...
+   Confidential clients also authenticate (client secret, or better private_key_jwt / mTLS).
+
+5. Validate the ID token (OIDC), then create your own session.
+```
+
+## ID token validation (OIDC Core)
+
+1. Signature verifies against a key from the provider's `jwks_uri` (cache keys; refetch on unknown `kid`). Algorithm is in your allow-list, never `none`.
+2. `iss` equals the expected issuer exactly.
+3. `aud` contains your `client_id`; if multiple audiences, `azp` equals your `client_id`.
+4. `exp` is in the future; `iat` is recent.
+5. `nonce` equals the value stored in the session.
+6. Identify the user by `iss` + `sub`. Email is not a stable identifier and may be unverified.
+
+Most libraries do all of this; confirm the one you use does and that you have not disabled any check.
+
+## Client types
+
+| Client | Credentials | Notes |
+|---|---|---|
+| Server-side web app | Confidential (secret or key) | Still use PKCE. Tokens stay on the server; browser gets a session cookie. |
+| SPA | Public | Best: backend-for-frontend holds tokens. Otherwise PKCE, in-memory tokens, refresh token rotation, short lifetimes. |
+| Native / mobile | Public | System browser (ASWebAuthenticationSession, Custom Tabs), never an embedded web view. Claimed HTTPS redirect (universal/app links) or loopback for desktop. |
+| Machine to machine | Confidential | `client_credentials` grant; no user, no refresh token. |
+
+## Pitfalls
+
+- **Open redirect via redirect_uri**: register exact URIs; never accept wildcards or a user-supplied return URL without an allow-list. After login, only redirect to relative paths you validate.
+- **Account takeover by email linking**: linking a social login to an existing local account by email alone lets anyone who controls that email at a sloppy provider take the account. Link by `iss` + `sub`, and require the user to sign in to the existing account to link it.
+- **Leaking codes or tokens**: no tokens in URLs or fragments, set `Referrer-Policy: no-referrer` (or strict) on the callback page, never log the callback query string.
+- **Over-broad scopes**: request only what you use; incremental consent for more.
+- **Access token as identity**: for "who is the user", use the ID token or `userinfo`, not an access token meant for an API.
+- **Using the provider's access token as your session**: create your own session after login; the provider's tokens are for calling the provider.
+- **Refresh tokens**: rotate on use with reuse detection, or sender-constrain them (DPoP, RFC 9449, or mTLS) where the provider supports it.
+- **Logout**: end your own session; use the provider's RP-initiated logout endpoint if single sign-out is required.
+
+## Grants never to implement
+
+- Implicit (`response_type=token`): tokens in the URL fragment, no PKCE binding.
+- Resource owner password credentials: your app sees the user's provider password; defeats MFA and phishing resistance.