@ponharu/pkgflare 1.1.2 → 1.2.0

package/docs/architecture.md

@@ -34,7 +34,7 @@ Secrets provide a small deployment-owned token set with registry-wide read or pu
 
 pkgflare uses the GitHub JWT directly as the npm Bearer token. A token exchange would shorten or reshape the credential but would also require a pkgflare signing key, a new session endpoint, and another token lifecycle. Direct verification keeps standard npm/Bun requests, retains GitHub's short expiry, and makes GitHub's fixed issuer/JWKS the only signing trust root. JWKS fetches are bounded, cached, and fail closed.
 
-Normal and reusable workflows are separate trust cases. A normal rule requires the absence of `job_workflow_ref`; a reusable rule matches both the caller's `workflow_ref` and the called `job_workflow_ref`. The called workflow may be pinned to its full commit SHA without changing the caller's branch/tag claim rules. Pull-request contexts are not accepted. Immutable numeric repository and owner IDs are authoritative; workflow path claims add execution constraints rather than replacing identity.
+Rules with and without `jobWorkflowRef` are separate trust cases. Omitting it requires the JWT claim to be absent; setting it requires the configured workflow identity and ref rule to match. GitHub-issued tokens can include `job_workflow_ref` for a job defined directly in a workflow, where it normally identifies the same workflow as `workflow_ref`. For a reusable job, `workflow_ref` identifies the caller and `job_workflow_ref` identifies the called workflow. The called workflow can use `@*` to accept any valid Git ref or full commit SHA without wildcarding its owner, repository, or path; an exact SHA remains available as an additional registry-side revision constraint. Pull-request contexts are not accepted. Immutable numeric repository and owner IDs are authoritative; workflow path claims add execution constraints rather than replacing identity.
 
 Unexpected diagnostics identify the request and operation without recording credentials or package payloads. Normal authenticated metadata responses do contain package manifests; the privacy restriction applies to diagnostics and error responses.
 

package/docs/operations.md

@@ -103,31 +103,35 @@ githubOidc: {
     repositoryOwnerId: "987654321",
     ref: "refs/tags/v*",
     workflowRef: "acme/example/.github/workflows/publish.yml@refs/tags/v*",
+    jobWorkflowRef: "acme/example/.github/workflows/publish.yml@*",
     permissions: ["publish"],
     packages: ["@acme/example"],
   }],
 }
 ```
 
-Repository and owner IDs are decimal GitHub IDs and remain the primary repository identity checks across renames. `ref` and `workflowRef` accept branch or tag refs; they are exact matches unless they end in `*`, in which case only that final prefix wildcard is supported. `jobWorkflowRef` accepts the same refs or an exact 40-character lowercase hexadecimal commit SHA. Package grants are exact scoped package names or a complete scope wildcard such as `@acme/*`; they must belong to a configured registry scope.
+Repository and owner IDs are decimal GitHub IDs and remain the primary repository identity checks across renames. `ref` and `workflowRef` accept branch or tag refs; they are exact matches unless they end in `*`, in which case only that final prefix wildcard is supported. `jobWorkflowRef` accepts the same refs, an exact 40-character lowercase hexadecimal commit SHA, or `@*` after an exact owner/repository/workflow path. Package grants are exact scoped package names or a complete scope wildcard such as `@acme/*`; they must belong to a configured registry scope.
 
 The complete normalized registry configuration must fit Cloudflare's 5 KiB per-variable limit. pkgflare checks this before deployment; prefer a scope wildcard or another registry when a very large subject/package matrix would exceed it.
 
-For a normal workflow, omit `jobWorkflowRef`. A token containing `job_workflow_ref` will not match that rule. For a reusable workflow, set all of these independently:
+`jobWorkflowRef` is optional in the configuration, but omission is an explicit requirement that the token does not contain `job_workflow_ref`; it is not a wildcard. GitHub-issued tokens can include `job_workflow_ref` for jobs defined directly in a workflow. In that case, set `jobWorkflowRef` to that workflow's ref, which normally matches `workflowRef` as shown above. Omit it only for an execution environment whose tokens do not contain the claim.
+
+For a reusable workflow, set the caller and called workflow refs independently:
 
 - `repositoryId`, `repositoryOwnerId`, `ref`, and `workflowRef` identify and constrain the caller.
 - `jobWorkflowRef` identifies the called reusable workflow and its trusted ref.
 
-Pin the reusable workflow to its full commit SHA when possible:
+To allow routine commit-SHA updates for one reusable workflow without changing the registry policy, fix its complete identity and wildcard only the ref:
 
 ```ts
 {
-  jobWorkflowRef:
-    "acme/workflows/.github/workflows/npm-publish.yml@0123456789abcdef0123456789abcdef01234567",
+  jobWorkflowRef: "acme/automation/.github/workflows/publish.yml@*",
 }
 ```
 
-GitHub keeps the caller information in the standard claims and puts the called workflow reference in `job_workflow_ref`. A reusable workflow may be called by branch, tag, or SHA; GitHub recommends a commit SHA as the safest option for stability and security. See GitHub's documentation for [OIDC with reusable workflows](https://docs.github.com/en/actions/how-tos/secure-your-work/security-harden-deployments/oidc-with-reusable-workflows) and [calling reusable workflows](https://docs.github.com/en/actions/how-tos/reuse-automations/reuse-workflows#calling-a-reusable-workflow).
+This wildcard cannot replace any part of the owner, repository, or workflow path. A matching JWT must still contain a valid full commit SHA, branch ref, or tag ref, and every repository ID, owner ID, caller ref/workflow, permission, and package grant in the subject must also match. Continue pinning the reusable workflow's `uses` entry to a full commit SHA; `@*` only avoids duplicating that changing revision in the registry policy.
+
+Set `jobWorkflowRef` to a full commit SHA instead when the registry policy must independently require that one revision. That stricter option requires a policy deployment whenever the reusable workflow SHA changes. GitHub keeps the caller information in the standard claims and puts the called workflow reference in `job_workflow_ref`; its trust examples also support filtering a fixed reusable workflow repository with a wildcard ref. See GitHub's documentation for [OIDC with reusable workflows](https://docs.github.com/en/actions/how-tos/secure-your-work/security-harden-deployments/oidc-with-reusable-workflows) and [calling reusable workflows](https://docs.github.com/en/actions/how-tos/reuse-automations/reuse-workflows#calling-a-reusable-workflow).
 
 OIDC requests from `pull_request`, `pull_request_target`, related pull-request events, and merge queues are rejected even if another claim pattern would match. Use a trusted branch, tag, or manually dispatched workflow. A `publish` grant includes reads and dist-tag changes only for its allowed packages; a `read` grant cannot publish or change tags. Metadata and tarball reads apply the same package grant.
 

package/docs/specification.md

@@ -89,7 +89,7 @@ Every Registry operation requires a Bearer token. Static tokens are compared aga
 
 When GitHub OIDC is configured, a non-Secret Bearer token may be a GitHub JWT. The Worker accepts only RS256 with JWT type, the fixed `https://token.actions.githubusercontent.com` issuer and fixed GitHub JWKS URL, the configured audience, required timing and identity claims, and a maximum issued age of ten minutes. It matches numeric repository and owner IDs, branch/tag ref, caller workflow, optional reusable workflow, permission, and package. Pull-request-related and merge-group events are rejected.
 
-Normal workflow rules require `job_workflow_ref` to be absent. Reusable workflow rules require it to match `jobWorkflowRef` in addition to matching the caller's `workflow_ref`. Caller workflow refs accept exact or terminal-wildcard branch/tag refs. A reusable workflow ref additionally accepts an exact full 40-character lowercase hexadecimal commit SHA; shortened or malformed SHAs are rejected. OIDC package grants are enforced before metadata, tarball, publish, and dist-tag handlers.
+Rules that omit `jobWorkflowRef` require `job_workflow_ref` to be absent from the token; omission does not disable matching for that claim. Rules that set it require a match in addition to `workflow_ref`. GitHub-issued tokens may include `job_workflow_ref` for jobs defined directly in a workflow, in which case the configured value normally matches that workflow's `workflow_ref`. For reusable jobs, `workflow_ref` identifies the caller and `job_workflow_ref` identifies the called workflow. Caller workflow refs accept exact or terminal-wildcard branch/tag refs. A job workflow ref additionally accepts an exact full 40-character lowercase hexadecimal commit SHA or a complete-ref wildcard written as `owner/repository/.github/workflows/file.yml@*`. The wildcard does not apply to the workflow identity, and the JWT claim must still end in a valid full SHA, branch ref, or tag ref. Shortened or malformed SHAs and wildcarded owners, repositories, or paths are rejected. OIDC package grants are enforced before metadata, tarball, publish, and dist-tag handlers.
 
 GitHub keys are fetched under timeout and response-size/key-count limits, cached per isolate, and refreshed after a cooldown when an unknown key is encountered. Invalid signatures/claims fail with 403. JWKS retrieval and validation failures fail closed with 503. Tokens and claims are not included in diagnostics.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ponharu/pkgflare",
-  "version": "1.1.2",
+  "version": "1.2.0",
   "description": "Deploy a private npm registry to your own Cloudflare account.",
   "keywords": [
     "cloudflare",