feat(auth0): split large references into hub+leaf groups (reference depth)#151
Draft
frederikprijck wants to merge 61 commits into
Draft
feat(auth0): split large references into hub+leaf groups (reference depth)#151frederikprijck wants to merge 61 commits into
frederikprijck wants to merge 61 commits into
Conversation
|
Important Review skippedDraft detected. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: ASSERTIVE Plan: Pro Plus Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
# Conflicts: # plugins/auth0/skills/auth0/references/framework-aspnetcore-auth.md # plugins/auth0/skills/auth0/references/framework-expo.md # plugins/auth0/skills/auth0/references/framework-go.md # plugins/auth0/skills/auth0/references/framework-java-mvc.md # plugins/auth0/skills/auth0/references/framework-php-api.md # plugins/auth0/skills/auth0/references/framework-react.md
frederikprijck
marked this pull request as draft
July 20, 2026 12:38
The #144 merge modified flat reference files this branch had already split into hub+leaf groups (modify/delete conflicts). The delete side was committed in the merge (3b6ddaf) but the manual ports into the leaf files were left uncommitted. Commit them: your-*.com placeholders -> RFC-2606 example.com forms in go/patterns, react/patterns, php-api/integrate, aspnetcore-auth/patterns, expo/patterns, java-mvc/api-reference.
# Conflicts: # plugins/auth0/skills/auth0/references/framework-java-mvc.md
frederikprijck
force-pushed
the
worktree-reference-depth
branch
from
July 20, 2026 16:04
97d340b to
bd1b08e
Compare
✅ skillsaw — All checks passedFull report
|
The proof-case swift group was carved before the document-section leaf axis was standardized. Two structural issues fixed: - index.md folded the whole Setup Guide into the hub -> extracted to setup.md; index.md is now a lean 47-line hub (rules + prereqs + when-not + dispatch) matching react/android. - integrate.md was three concatenated docs (Integration + API Reference & Testing + Integration Patterns) plus a stray migration-flavored Common Mistakes tail -> split into integrate.md / api-reference.md / patterns.md; the migration tail moved into migration.md. Lossless: 82 code fences in = 82 out; all API tables and pattern sections preserved. Hub dispatch adds setup/api-reference/patterns 'Then, as needed' rows. Reachability + routing-evals + 50 unit tests + validate-skill.sh pass.
The 'Adding a reference' section pointed contributors at tests/routing-cases.json, which does not exist. The file lives at repo-root evals/routing-cases.json -- what CI (.github/workflows/skillsaw.yml) and the checker's fallback actually read.
The uniform-folder refactor made every reference a <name>/ directory, but the naming-convention prose in AGENTS.md, CONTRIBUTING.md, and the check_router_reachability.py docstring still wrote framework-<name>.md etc. Update them to directory form for consistency with the shipped layout.
…leaf The framework-nuxt leaf-group carve moved route-protection, session-store, and advanced-example content into patterns.md, but integrate.md still said 'see the ... section below' — the content is no longer below. Restore the pre-v2 'secondary, reachable via pointer' design (definePageMeta was always in a separate route-protection leaf, never the primary path) by pointing at 'this group's patterns guide' instead, matching the other leaf groups' convention. The hub index.md already routes advanced seekers to patterns.md. Also drop the stale 'Common Examples' label (no such section post-carve).
frederikprijck
force-pushed
the
worktree-reference-depth
branch
from
July 24, 2026 09:38
0d7658d to
edec431
Compare
…overable The hub's only machine-followable pointer to patterns.md labelled it 'advanced route-protection / session-store patterns', which reads as optional — so an agent doing a quickstart with a protected page didn't load patterns.md and missed the page-level definePageMeta middleware it needed. Relabel the pointer to name definePageMeta/page protection explicitly and note integrate.md covers only baseline global/server middleware. Keeps the pre-v2 design (definePageMeta stays out of the primary integrate path, reachable via the hub) while closing the discoverability gap.
…reference (+migration) Reduce leaf sprawl: fold setup.md, patterns.md, and the tiny mfa.md into integrate.md (Setup / Integration Patterns / MFA sections), keeping only the API/config lookup (api-reference.md) and the eval-required migration.md as separate leaves. Lossless — every section, code block, and table preserved; in-file cross-references rewritten from 'this group's X leaf' to 'the X section below'. Hub dispatch updated: feature:mfa now routes to integrate.md. Target shape for all leaf groups: index.md + 2 content leaves (+migration where the SDK has a major-version upgrade). Proof case for the rest.
Apply the framework-swift recipe (a9fb663) across the remaining 13 leaf groups so every group is index.md + exactly 2 content leaves, with migration.md as the only allowed 3rd exception (android, swift). Framework groups (android, aspnetcore-auth, expo, go, ionic-angular, ionic-vue, java-mvc, php-api, php, react): fold setup.md + patterns.md into integrate.md (## Setup, ## Integration Patterns); keep api-reference.md; keep migration.md untouched for android. Feature groups: feature-branding folds templates->guide, examples-> api-reference; feature-custom-domains folds advanced->guide, examples-> api-reference; feature-acul folds patterns->guide and cli-reference-> sdk-reference, then renames sdk-reference->api-reference. Lossless (every section preserved), in-file cross-refs rewritten to '... section below', hub dispatch tables repointed to surviving leaves. Leaf-sink invariant, routing evals, reachability, and skillsaw --strict all green. Follow-up PR will add per-file Tables of Contents.
Relocate each framework leaf group's Quick Start Workflow up from integrate.md into the hub index.md as `## Quick start`, so the hub is immediately actionable without a second read. Depth (setup variants, Common Mistakes, pattern catalog) stays in integrate.md. Dispatch tables unchanged; same-file cross-refs rewritten to prose role references to preserve the leaf-sink rule. Groups: react, android, go, php, php-api, expo, ionic-angular, ionic-vue, java-mvc, aspnetcore-auth (Blazor/Razor variants retained in integrate.md), nuxt (Quick Setup + Built-in Routes + Composables moved; Protecting Routes depth retained).
…ntation inline) Relocate orientation front-matter up from guide.md into the hub index.md for feature-branding, feature-custom-domains, and feature-acul, matching the pre-v2 SKILL.md standalone shape. The detailed capability/phase playbooks stay in guide.md; dispatch rows unchanged. - branding: moved Capabilities, Prompt style, Plan mode, Verify-in-browser, Key Concepts, Prerequisites, capability dispatch entries, Common Mistakes, References (boundary: first # Capability H1). Rewrote stale SKILL.md cross-refs to hub-index prose. - custom-domains: moved Overview, Interaction style, Error-code triage, Capabilities, Key Concepts, Prerequisites, Common Mistakes (boundary: ## Advanced, keeping MCD/certs/DNS-playbook depth in guide.md). - acul: moved Reference Hierarchy, auth0-acul-samples Architecture, Prerequisites (boundary: ## Phase 0); removed a pre-existing duplicate Prerequisites block; rewrote same-file refs that became cross-file.
…sections The go hub carried standalone ## Install SDK and ## Configure .env sections predating this feature; the relocated ## Quick start repeats both verbatim (Steps 1 and 3). Drop the duplicates so go matches the swift template shape (Critical rules → Prerequisites → When NOT to Use → Quick start → Choose your task). Final-review Minor finding.
…tent Replace architecture jargon with plain doc roles throughout the skill: - '# Auth0 X — reference hub' title suffix dropped (matches index-only refs) - 'hub'/'hub index' -> 'overview'; 'guide leaf' -> 'guide'; 'api-reference leaf' -> 'API reference'; 'migration leaf' -> 'migration guide' - 'read the leaf'/'Read only the leaf (or leaves)' -> 'reference(s)' - SKILL.md routing note: 'intent->leaf'/'single leaf' -> 'document' No structural change; dispatch tables and routing unchanged.
The callout restated what each Step 4 intent block already emits
(explicit references/{name}/index.md paths) and what each index.md's
own '## Choose your task' section conveys on arrival. Migration-era
scaffolding; trimming it lightens the always-loaded router.
Generated lockfile for the dev-only behavioral eval harness; keep it out of version control (file remains on disk).
![semgrepcode-auth0[bot]](https://avatars.githubusercontent.com/in/977730?s=60&v=4){kind=small}
| if [[ "$OSTYPE" == "darwin"* ]]; then | ||
| brew install auth0/auth0-cli/auth0 | ||
| else | ||
| curl -sSfL https://raw.githubusercontent.com/auth0/auth0-cli/main/install.sh -o /tmp/auth0-install.sh |
There was a problem hiding this comment.
Semgrep identified an issue in your code:
Installation script downloaded to world-writable /tmp directory can be replaced by local attackers before execution, allowing credential theft during subsequent auth0 login step.
More details about this
The curl command downloads an installation script directly to /tmp/auth0-install.sh, which is a world-writable temporary directory. An attacker with local access to the system could exploit this in several ways:
-
Pre-execution replacement: Before the script runs (the
sh /tmp/auth0-install.shline), an attacker with local access to/tmpcould replace/tmp/auth0-install.shwith a malicious script that installs a backdoor or exfiltrates credentials instead of installing the Auth0 CLI. -
Race condition: An attacker could monitor
/tmpfor the creation ofauth0-install.sh, quickly replace it with malicious code, and have that code execute with the same privileges as the parent shell script—potentially with elevated privileges if this runs as root. -
Persistence: Since
/tmpis often world-writable and world-readable, an attacker could plant a trojanized version of the script there and wait for legitimate users to run this installation process, compromising multiple systems and stealing credentials during the Auth0 login step (auth0 loginwill prompt for credentials that could be intercepted).
The vulnerability is particularly severe because the script later calls auth0 login, which will prompt for sensitive authentication credentials that could be stolen if the downloaded script has been compromised.
To resolve this comment:
✨ Commit fix suggestion
Suggested change
| curl -sSfL https://raw.githubusercontent.com/auth0/auth0-cli/main/install.sh -o /tmp/auth0-install.sh | |
| curl -sSfL https://raw.githubusercontent.com/auth0/auth0-cli/main/install.sh | sh -s -- -b /usr/local/bin |
View step-by-step instructions
- Replace the
curldownload-to-/tmppattern with a direct pipe tosh, which avoids writing an executable script to a temporary path entirely: change the three lines (curl ... -o /tmp/auth0-install.sh,echo "Review...",sh /tmp/auth0-install.sh ...) tocurl -sSfL https://raw.githubusercontent.com/auth0/auth0-cli/main/install.sh | sh -s -- -b /usr/local/bin.
Alternatively, if you want to keep the review step for auditability, download the script to the current working directory instead of /tmp: use -o ./auth0-install.sh and then run sh ./auth0-install.sh -b /usr/local/bin && rm ./auth0-install.sh. Writing to the project directory rather than /tmp avoids the hidden-staging-path pattern that malware commonly exploits.
💬 Ignore this finding
Reply with Semgrep commands to ignore this finding.
/fp <comment>for false positive/ar <comment>for acceptable risk/other <comment>for all other reasons
Alternatively, triage in Semgrep AppSec Platform to ignore the finding created by skill-download-tmp-exec.
You can view more details about this finding in the Semgrep AppSec Platform.
The index-only and grouped framework loops asserted the identical condition (framework-<name>/index.md exists); neither verified a leaf, so the split distinguished nothing the script checks. Collapse to one EXPECTED_FRAMEWORKS roster. Real hub/leaf structure is enforced by check_router_reachability.py.
Same redundancy as the framework loops: the index-only and grouped feature loops both asserted only that feature-<name>/index.md exists. Collapse to one EXPECTED_FEATURES roster (organizations stays separate for its line-count check).
The merged rosters now carry the same members as main; reorder them to main's sequence so the diff is limited to the loop consolidation, not a spurious reordering.
Ported from origin/main e295fd6 into the carved layout. The stray ')' after the packageId assignment survived on this branch (predates the fix); it lives in the hub index.md logout snippet, not a leaf.
Ported from origin/main b472904 into the carved layout. Two hunks: the runtimeConfig comment lands in the hub index.md's nuxt.config.ts block; the anti-hardcoding Common-Mistakes row lands in integrate.md (where the mistakes table now lives after the split).
) Ported from origin/main 7e9ce86 into the carved layout. Both logout samples (quick-start in index.md, detailed in integrate.md) had onSuccess(result: Void) under a Callback<Void?, ...> type parameter — the nullability mismatch fails Kotlin compilation.
…rence (#157) Ported from origin/main a3e0db8 into the carved layout. Three hunks: the quick-start IMPORTANT note in index.md, the anti-hardcoding Common-Mistakes row in integrate.md, and the api-reference.md replacement of the literal-credential getInstance("CLIENT_ID","DOMAIN") variant with strings.xml-only guidance.
Ported from origin/main d1b1985 into the carved layout. The claims example used IDTokenClaimsValidation().validate() — an internal validation helper, not a public claims API. Replace with credentialsManager.user (UserInfo?) plus a JWTDecode manual-decode example. Lands in the swift api-reference.md leaf.
Ported from origin/main 97b9d9a into the carved layout. Two hunks: the never-pass-credentials-in-code IMPORTANT blockquote after the automatic/manual choose block in index.md, and the anti-hardcoding Common-Mistakes row in integrate.md.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What & why
Large reference files forced an agent to load ~100K of tokens even when it needed one section. This introduces one level of depth: references over ~40K become hub + leaf groups so the router pulls only the slice a task needs.
A reference is now either a flat
*.mdfile or a group directory<stem>/with:index.md— a hub: shared prerequisites + an imperative intent→leaf dispatch tableintegrate.md,api-reference.md,patterns.md,setup.md,migration.md; features split by sub-topic)Navigation is a depth-2 tree: the router reads the hub, which dispatches to exactly one leaf (two hops). A hub may dispatch only to leaves in its own directory; leaves and flat files link to nothing; cross-group links are forbidden. This relaxes the previous strict one-hop rule in a bounded, enforced way.
Changes
framework-swift(proof case),android,go,php-api,php,react,java-mvc,ionic-angular,ionic-vue,aspnetcore-auth,expo,nuxt, and featurescustom-domains,branding,acul. Every carve is byte-lossless.scripts/check_router_reachability.py— recursive discovery, two-level orphan/broken-route checks, and a newSIDEWAYS_TWO_LEVEL_RE(the shared single-level regexes exclude/, so they can't see<group>/<leaf>.mdtargets). Backward compatible with flat files.scripts/check_routing_evals.py— resolves a grouped slug to<stem>/index.md+ the intent's leaf (read from the hub's dispatch table).SKILL.md— one global note in Step 4 telling the agent to readindex.mdwhen a target is a group directory; per-intent routing tokens unchanged.AGENTS.md,CONTRIBUTING.md(new "Adding a grouped reference" section),docs/architecture.md,PLUGIN.mdupdated to the two-hop-through-hub model.Validation
Deterministic gates (all green):
check_router_reachability.py— PASScheck_routing_evals.py— PASS (30 cases)validate-skill.sh— PASSskillsaw --strict— Grade A, 0 errorsBehavioral evals (live agent, with-skill vs without-skill delta) confirm the two-hop dispatch works end-to-end. Every grouped framework that ran cleanly shows the skill helping, with no regression on flat files:
Flat-file regression check: ionic-react +19, flutter-native +17, flutter-web +15, flask +15, spa-js +5, express-jwt +1 — no regressions.
Known follow-ups (not blocking)
swift-migration,android-migration) score low purely because their judge graders time out — the cases compile the project, flooding the 60sclaude -pjudge with.build/+ SDK-checkout noise. Objective graders pass and migrated files are correct. This is a pre-existing eval-harness limitation (judges should exclude.build//node_modules//checkouts), not a defect in the migration leaves.framework-swift/index.md(~16K) folded its Setup Guide into the hub instead of extracting asetup.mdleaf — it was the proof case, carved before the document-section leaf axis was standardized. Worth a follow-up re-carve so the reference implementation matches the pattern the other 14 groups use.