Guidewire Install AuthSAFE

Model-agnostic agent-skills platform with a harness-free canonical layer, verified adapters, and the ccpi package manager. Explore at tonsofskills.com.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: guidewire-install-auth
description: Authenticate production Guidewire Cloud API integrations and survive the auth-side failures — token expiry storms, scope drift, private-CA PKIX errors, secret rotation. Use when hardening OAuth2 token caching, configuring JVM trust stores, or rotating client secrets without downtime. Trigger with "guidewire auth", "guidewire OAuth2", "guidewire token cache", "guidewire PKIX", "guidewire secret rotation".
allowed-tools: Read, Write, Edit, Bash(curl:*), Bash(jq:*), Bash(java:*), Bash(keytool:*), Bash(openssl:*), Grep
version: 1.26.0
license: MIT
author: Jeremy Longshore <[email protected]>
compatibility: Designed for Claude Code
tags:
  - guidewire
  - oauth2
  - authentication
  - token-management
  - secret-rotation
  - pkix
---

# Guidewire Install & Auth

## Overview

Authenticate a backend service to a Guidewire Cloud tenant using OAuth2 client credentials and operate the auth layer in production. This is not a hello-world walkthrough; it is the auth code your service runs at 3am when a token expires mid-batch, when a tenant admin rotates a scope, when a private CA renews a cert, and when on-call needs to swap a leaked secret without dropping in-flight requests.

The four production failures this skill prevents:

1. **Token expiry storms** — every request races to refresh, the Hub rate-limits the auth endpoint, the integration cascades to red.
2. **Scope drift** — a GCC admin removes a scope, every cached token starts returning `403`, retrying does not help.
3. **PKIX path building failed** — JVM cannot validate the tenant's TLS chain because the private CA is not in the trust store; common when carriers front Cloud API with their own DLP appliance.
4. **Secret rotation downtime** — the active client secret is rotated and the old secret stops working before the new one is loaded; in-flight token refreshes fail until restart.

## Prerequisites

- JDK 17 (Guidewire Cloud release `202503` and later)
- A registered **Service Application** in Guidewire Cloud Console (GCC) with Cloud API roles assigned per least privilege
- Network egress from your runtime to `*.guidewire.net` (runtime APIs) and `gcc.guidewire.com` (console only)
- A secret store the runtime can read at startup and on rotation signal (AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault, or Kubernetes Secret with CSI driver)
- For private-CA tenants: the carrier's CA chain in PEM form

## Instructions

Build the auth layer in this order. Each section solves one production failure mode; do not skip steps because the failure shows up in production, not in dev.

1. Implement the **token-cache pattern** below — proactive refresh, single-flight gate, JWT-based expiry.
2. Wire **secret rotation** to your secret store; do not commit secrets or bake them into images.
3. For private-CA tenants, install the **trust store** at the JVM/init-container layer.
4. Validate **scope hardening** on every refresh so drift fails fast, not on the next business call.

### Token-cache pattern (production)

Tokens are short-lived, typically one hour. Reactive refresh on `401` is wrong: it doubles latency on the failing request and creates a thundering herd when many requests notice expiry simultaneously. Cache the token in-process and refresh **proactively** at 80% of TTL, behind a single-flight gate so concurrent refreshers serialize.

```typescript
import jwt from "jsonwebtoken";

type Cached = { value: string; expiresAt: number };
let cached: Cached | null = null;
let inflight: Promise<string> | null = null;

export async function getToken(): Promise<string> {
  if (cached && Date.now() < cached.expiresAt - 60_000) return cached.value;
  if (inflight) return inflight;

  inflight = (async () => {
    const res = await fetch(process.env.GW_AUTH_URL!, {
      method: "POST",
      headers: { "Content-Type": "application/x-www-form-urlencoded" },
      body: new URLSearchParams({
        grant_type: "client_credentials",
        client_id: process.env.GW_CLIENT_ID!,
        client_secret: process.env.GW_CLIENT_SECRET!,
        scope: process.env.GW_SCOPES!,
      }),
    });
    if (!res.ok) throw new Error(`auth ${res.status}: ${await res.text()}`);
    const { access_token } = await res.json();
    const { exp } = jwt.decode(access_token) as { exp: number };
    // exp is seconds since epoch; multiply by 1000 for JS ms. Refresh at 80% of remaining TTL.
    const expMs = exp * 1000;
    cached = { value: access_token, expiresAt: expMs - 0.2 * (expMs - Date.now()) };
    return access_token;
  })().finally(() => { inflight = null; });

  return inflight;
}
```

The `exp - 20%` early-refresh window absorbs clock skew and prevents the cliff at TTL boundary. The `inflight` single-flight gate makes a high-rps service issue one refresh per cache-miss, not one per concurrent request — without it, a 1000-rps service produces 1000 simultaneous Hub calls and trips `429` rate-limiting on the auth endpoint.

### Secret rotation without downtime

Rotation breaks if the runtime reads the secret only at startup, or if the plaintext lives somewhere reviewable (committed `.env`, container image layer, unencrypted Kubernetes `Secret`). Three patterns work, in order of operational simplicity:

**SOPS + age (recommended for VM/container deployments).** Encrypt `secrets.prod.sops.yaml` with one or more age public keys, commit the encrypted file to git, decrypt in-process at startup and on `SIGHUP`. The repo holds an auditable history of who rotated what and when; only holders of the age private key can read plaintext. Bootstrap a repo with the same conventions used across this organization:

```text
sops-init                                    # idempotent; writes .sops.yaml + .env.sops + scripts/sops-env
sops secrets.prod.sops.yaml   # interactive edit; ciphertext re-written on save
eval "$(sops -d secrets.prod.sops.yaml | sed -nE 's/^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/export \1=\2/p')"
```

The anchored `sed` reg

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (2)

POST https://hub.[TENANT].guidewire.net/oauth/token

cat > .env << 'EOF'

Gates applied: no_behavioural_pass.