Skip to content

refactor: group root packages by role (access, authz, http, proof)#60

Merged
jmgilman merged 7 commits into
masterfrom
reorg/package-layout
May 27, 2026
Merged

refactor: group root packages by role (access, authz, http, proof)#60
jmgilman merged 7 commits into
masterfrom
reorg/package-layout

Conversation

@jmgilman
Copy link
Copy Markdown
Contributor

Summary

Reorganize the 17 flat root packages into four conceptual buckets so the layout telegraphs each package's role:

access/{jwt,middleware}        # was accessjwt, accessjwtauth
authz/{role,casbin}            # was roleauth, casbin
http/{auth,facts,compose}      # was httpauth, httpfacts, compose
proof/{oidc,passkey,apikey}    # was oidc, passkey, apikey (passkey/session under proof/passkey/)
exchange/                      # unchanged
onboarding/                    # unchanged
provisioning/                  # unchanged
management/                    # unchanged
store/                         # unchanged
testkit/                       # unchanged

There are no external consumers; this is the cheapest moment to do this. The change is purely mechanical: no logic, no schema, no port, no exported-symbol changes beyond their package qualifiers.

What changes

  • Five packages have their package name changed alongside the path move:
    • accessjwt -> access/jwt (package accessjwt -> jwt)
    • accessjwtauth -> access/middleware (package accessjwtauth -> middleware)
    • roleauth -> authz/role (package roleauth -> role)
    • httpauth -> http/auth (package httpauth -> auth)
    • httpfacts -> http/facts (package httpfacts -> facts)
  • The remaining six (compose, oidc, passkey, passkey/session, apikey, casbin) keep their package names; only the import path changes.
  • Internal error-prefix strings updated for renamed packages ("accessjwt: ..." -> "jwt: ..." etc.). No consumer matches these via string comparison.
  • One prep commit (e3879f1) introduces a jwxjwt alias for github.com/lestrrat-go/jwx/v3/jwt inside accessjwt/ to free the jwt package name without colliding with the third-party import. Same trick was needed in testkit/internal/httpui/server_test.go.
  • One sundry test fix: http/facts/facts_test.go's local merged-result variable renamed facts -> got to avoid shadowing the newly-renamed package.
  • Root doc.go now lists the four subgroups so newcomers can scan the layout at a glance. Docusaurus pages and per-package sibling-mentioning doc.go files updated.

Verification

  • moon run root:check --summary minimal — green (format, lint, build, unit tests).
  • moon run root:integration — green (Testcontainers postgres exercises the storage suite against the relocated proof/* packages).
  • moon run docs:typecheck && moon run docs:build — green.
  • Exported-surface diff for all 11 renamed packages: identical (no symbols accidentally renamed). Compared go list -f exports against master.
  • git grep for old import paths and symbol prefixes in *.go and docs/docs/**/*.md: clean.

Out of scope

  • internal/authtest, internal/storetest — internal helpers, left at root.
  • store/memory, store/postgres — already grouped, untouched.
  • testkit/ — internal validation app, left at root.
  • management/, exchange/, onboarding/, provisioning/ — already meaningful top-level names; no parent buys clarity.
  • CHANGELOG.md, PLAN.md — historical artifacts, left alone.

Test plan

  • go build ./... clean.
  • moon run root:check --summary minimal clean.
  • moon run root:integration clean.
  • moon run docs:build clean.
  • Spot-check go doc github.com/meigma/authkit/access/jwt (and friends) shows the same symbol surface as the old packages.
  • Concurrent worktree on feat/httpapi-auth-flow will need a one-time rebase after this merges.

🤖 Generated with Claude Code

jmgilman and others added 7 commits May 26, 2026 18:39
Free the package name "jwt" so accessjwt can move under access/ without
colliding with the lestrrat-go/jwx/v3/jwt import inside the package.

Mirrors the existing precedent in casbin/authorizer_test.go where
github.com/casbin/casbin/v2 is aliased as casbinv3.

No behavior change.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Group the three external-proof primitives (OIDC JWT verifier, WebAuthn
passkey ceremonies, opaque API tokens) under proof/ so the layout
telegraphs their shared role: producing authkit.Identity from raw
credentials. Package names are unchanged; only import paths shift.

No behavior change.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Group the two authorizer adapters under authz/. roleauth becomes
authz/role (package roleauth -> role) so the parent path carries the
"authorization" signal and the leaf no longer repeats it. casbin moves
to authz/casbin with its package name unchanged.

Internal error-prefix strings in the role package are updated from
"roleauth: ..." to "role: ...". No consumer matches on these strings
(everything uses errors.Is + sentinels).

No behavior change.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Group the access-token primitive and its HTTP authenticator under
access/. Package renames:

- accessjwt -> access/jwt (package accessjwt -> jwt)
- accessjwtauth -> access/middleware (package accessjwtauth -> middleware)

Symbol prefixes change at consumer call sites (accessjwt. -> jwt.,
accessjwtauth. -> middleware.). Internal error-prefix strings updated
to match the new package names ("jwt: ...", "middleware: ...").
compose/http_test.go assertion strings updated for the new wrapped
prefixes.

testkit/internal/httpui/server_test.go aliases the third-party
github.com/lestrrat-go/jwx/v3/jwt import as jwxjwt to avoid colliding
with our github.com/meigma/authkit/access/jwt import in the same file.

No behavior change.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Group HTTP plumbing under http/. Package renames:

- httpauth -> http/auth (package httpauth -> auth)
- httpfacts -> http/facts (package httpfacts -> facts)
- compose -> http/compose (package unchanged)

Symbol prefixes change at consumer call sites (httpauth. -> auth.,
httpfacts. -> facts.). Internal error-prefix in http/auth/middleware.go
updated to "auth: ...". compose's package name and error prefixes
unchanged.

http/facts/facts_test.go: renamed the local merged-result variable
from `facts` to `got` to avoid shadowing the package name after the
httpfacts -> facts rename.

No behavior change.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Refresh the root package overview, http/compose/doc.go,
proof/passkey/doc.go, and the Docusaurus pages so package names and
symbol prefixes match the new hierarchy.

The root doc.go now lists the four subgroups (access, authz, http,
proof) and the standalone bridge/management packages so newcomers can
scan the layout at a glance. Docusaurus prose now references full
subpaths (`access/jwt`, `http/auth`, etc.) and code snippets use the
new symbol prefixes (`jwt.NewVerifier`, `role.NewAuthorizer`,
`auth.NewMiddleware`, etc.).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
goimports -local github.com/meigma/authkit reorders the authkit
import group alphabetically. Mechanical follow-up to the four move
commits.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@jmgilman jmgilman merged commit 6bc6ed0 into master May 27, 2026
2 checks passed
@jmgilman jmgilman deleted the reorg/package-layout branch May 27, 2026 17:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant