DEV Community: Daniel Yang

You can't commit what Git can't see: keeping agent exhaust out of your repo

Daniel Yang — Tue, 21 Jul 2026 06:52:35 +0000

Working with coding agents produces exhaust. Plans written before any code gets touched. Research notes on the library that didn't make the cut. A script that verified one thing once. Instructions telling the agent how I like to work.

None of it belongs in the repo, but all of it wants to live right next to the repo.

For a while, I handled this the usual way: a .gitignore entry and good intentions.

The problem is that .gitignore is a promise, not a guarantee. One git add -f when you're moving fast. One overly broad pattern change that un-ignores a directory as a side effect. One agent that "helpfully" cleans up your ignore file during a refactor—which is a real thing that happens when you give a language model write access to your tree.

Any of those can put your private notes into history. Once that history reaches a shared remote, cleaning it up means rewriting commits, coordinating with everyone who pulled them, and possibly rotating anything sensitive.

So I stopped trusting the promise. My notes now live one directory above the repo root, outside its worktree entirely:

myapp-workspace/          ← workspace, outside the Git repo
├── CLAUDE.md             ← personal agent instructions
├── notes/                ← plans, research, session notes
├── scratch/              ← agent exhaust, one-off scripts
└── myapp/                ← the Git repo
    └── CLAUDE.md         ← optional, shared project instructions

Files in notes/ and scratch/ cannot be accidentally staged by commands operating on the repo. The protection doesn't depend on anyone remembering an ignore rule; the files are structurally outside the thing Git tracks.

What goes where

The workspace is a plain, untracked folder that wraps the repo.

notes/ holds anything durable: plans, research, and session summaries. scratch/ is the dumping ground for agent output and one-off experiments. Anything worth keeping graduates to notes/ or into the repo's own documentation. The repo itself is the only thing that ships.

CLAUDE.md is what makes the layout work well with agents. Claude Code loads instruction files from ancestor directories of wherever it starts, so a workspace-level CLAUDE.md is read by sessions inside the repo while remaining outside the repo's worktree.

Mine explains the layout and adds one important rule: never reference ../notes or ../scratch from anything committed inside the repo. The files can't be staged directly, but an agent could still copy or quote their contents. The instruction makes that boundary explicit.

The outer file doesn't replace a committed CLAUDE.md inside the repo. They serve different audiences: the workspace file holds personal preferences and rules specific to the wrapper, while an optional inner file can hold architecture, conventions, and gotchas that should travel with the code and be shared with the team. Claude reads both. Repoyard creates only the outer one; the inner file belongs to the project and its team.

Why the suffix goes on the outside

The workspace is named myapp-workspace, while the repo keeps the clean name myapp. I tried it the other way around first and walked it back for three reasons that all turned out to matter:

Terminal tabs usually show the innermost folder. With the clean name inside, tabs show myapp rather than some variation of workspace.
Tools derive names from the repo directory. Docker Compose project names, npm init defaults, and similar conventions stay clean.
The repo directory matches the GitHub repository name, so running git clone inside a fresh workspace recreates the layout without a custom target argument.

The wrapper gets the suffix because the wrapper is the unusual part. The repo keeps the name every other tool expects.

The tool

I wrote a small CLI that scaffolds the convention: repoyard. It has zero dependencies, requires Node 20 or newer, and provides three commands:

npx repoyard create myapp   # greenfield: workspace + fresh Git repo inside
npx repoyard adopt          # wrap an existing repo
npx repoyard doctor         # check a workspace against the convention

adopt is probably the command you'll use most, since most projects already exist.

Run it from the root of a clean repo and it creates the sibling workspace, moves the repo inside with a same-filesystem rename, and scaffolds the workspace files. If anything fails, it rolls the move back automatically. When it's done, it prints the cd command for the new location.

Run it interactively and it asks what you want using arrow-key menus. Pass --no-input to make it scriptable, or --dry-run to print the plan without touching anything. Pass --agent-file=claude|agents|both|none to scaffold AGENTS.md instead of—or alongside—CLAUDE.md, since the convention isn't Claude-specific.

The first repo I adopted was repoyard itself. The tool now lives inside the layout it scaffolds, which is either good dogfooding or a snake eating its tail, depending on your mood.

Yes, this is basically `mkdir`

You could set all of this up by hand in thirty seconds. The tool will not pretend otherwise.

What you're getting is the codified convention: the naming, the division between durable notes and disposable scratch work, and an agent-facing instruction file that explains the layout to any tool reading ancestor directories.

Conventions pay off when you, your agents, and your other machines all do the same thing without having to think about it. The syscalls were never the hard part.

The tool is also deliberately finished. There is no config file, plugin system, framework template, telemetry, or update checker. Worktrees already work fine inside a workspace:

git worktree add ../myapp-wip

Repoyard stays out of that too. Post-1.0 ideas have to solve a concrete problem, not merely exist.

If this failure mode has ever bitten you—or you'd prefer it never get the chance—you can find the project at github.com/ddyy/repoyard, or run npx repoyard in a scratch directory and try it yourself.

Beyond login: encrypting data with passkeys and WebAuthn PRF

Daniel Yang — Thu, 16 Jul 2026 21:24:05 +0000

Originally published at daniel-yang.com.

I've been using passkeys for a while now, and at some point I noticed an extension in the WebAuthn spec that almost nobody talks about: PRF. It lets a website ask your authenticator to evaluate a pseudo-random function during login. Deterministic output, 32 bytes, keyed to that specific credential, never leaves your browser.

That's an encryption key. Sitting inside the same ceremony everyone already uses for login.

So I built pknotes to see how far the idea goes: an end-to-end encrypted notes app with no master password anywhere. Your passkey unlocks your notes in the literal, cryptographic sense. This post is the architecture writeup. There's a live demo if you'd rather poke it first (notes wiped daily).

One ceremony, two jobs

A normal passkey login proves who you are and nothing else. With the PRF extension, the same ceremony does double duty:

The server verifies the WebAuthn assertion. That's login.
The client reads the PRF output from the same response and derives a key from it. That's decryption.

The server never sees the PRF bytes. They're returned to client-side JavaScript only, after user verification (Face ID, Touch ID, PIN), and only for the requesting origin.

Requesting it looks like this:

const credential = await navigator.credentials.get({
  publicKey: {
    challenge,
    userVerification: 'required',
    extensions: {
      prf: { eval: { first: new TextEncoder().encode('pknotes/prf-eval/v1') } },
    },
  },
});
const prfOutput = credential.getClientExtensionResults().prf.results.first;
// 32 bytes, deterministic for this credential + this input, never sent anywhere

The key hierarchy

Raw PRF output shouldn't encrypt data directly, and you also want to be able to add and remove devices without re-encrypting everything. So there's a small hierarchy:

Passkey PRF output
   │  HKDF-SHA256
   ▼
KEK (key-encryption key, exists only in browser memory)
   │  unwraps
   ▼
Master key (random AES-256, generated once at signup)
   │  AES-256-GCM, fresh IV per save
   ▼
Notes

The master key is random, not derived. Each passkey wraps its own copy of it, and those wrapped blobs are what the server stores. Three properties fall out of this:

Adding a device is one wrap, not a re-encryption. A new passkey does a ceremony, derives its own KEK, wraps the same master key, done. Your notes don't change. Passkeys sync through iCloud Keychain or Google Password Manager anyway, so most "new device" cases are free.

Recovery doesn't need a password either. At signup you get a one-time 160-bit recovery code. It's just another wrap of the master key, with the KEK derived from the code instead of a PRF. The server stores a hash of a verifier derived from the code, so the code itself works like a passkey that lives on paper. Codes are single-use: redeeming one invalidates it and issues a replacement.

Revocation is rotation. Deleting a stolen device's passkey row only blocks future logins; the thief may already hold the master key. Real revocation generates a fresh master key, re-encrypts every note, re-wraps for the one passkey you're holding, and cuts off everything else. In pknotes that's one button. It's the operation that makes "remove this device" mean something.

The detail that took me longest: bind ciphertext to context

Every note is encrypted with the same master key. Without extra care, a malicious server could swap the ciphertext of two notes and the client would decrypt the wrong content in the wrong place, silently. AES-GCM has a feature built for exactly this, additional authenticated data (AAD):

crypto.subtle.encrypt(
  { name: 'AES-GCM', iv, additionalData: enc.encode(`pknotes/note/v1:${noteId}`) },
  masterKey,
  plaintext,
);

The note's id is baked into the authentication tag. Serve that blob under any other note's id and decryption fails loudly instead of succeeding wrongly. Cheap to add, easy to forget, and the difference between "we encrypt" and a threat model that holds up.

What AAD doesn't cover: the server can still serve you an older version of the same note. Detecting that would need client-side version state. It's on the documented-limitations list, and I'd rather document it than pretend.

What actually supports PRF (mid-2026)

The provider matters more than the browser, because third-party password-manager extensions intercept WebAuthn:

Provider	PRF for third-party sites
iCloud Keychain (macOS 15+, iOS 18.4+)	✅ Yes
Google Password Manager	✅ Yes
1Password	✅ Yes
Windows Hello (Win 11 25H2+)	✅ Yes
YubiKey / FIDO2 keys	✅ Yes — except via Safari on iOS
Bitwarden, Dashlane, Proton Pass, KeePassXC	⏳ Not yet

Bitwarden is the one that'll bite you in practice. Its extension intercepts the WebAuthn ceremony, so it hijacks the flow even when the user has a working platform passkey (iCloud Keychain, Windows Hello) sitting right there — the others only matter if you deliberately picked them as your provider. pknotes detects the missing PRF and tells the user to dismiss the Bitwarden prompt and use a supported provider.

More generally: check for PRF at signup and refuse to create an account you could never decrypt. Do that check first; the failure mode otherwise is a user with an account and no key.

What this doesn't solve

The server ships the JavaScript. A malicious or compromised server could serve a client that exfiltrates keys, and that's true of every web-based E2EE product, Proton and Bitwarden's web vault included. My answer is structural rather than cryptographic: the client is about 1,500 lines with one crypto dependency, small enough to actually read, and self-hosting makes you the party you're trusting. A pinned native client is the only stronger answer, and the web can't provide one.

The server also sees metadata (note count, timestamps, sizes, IPs). And if you lose every passkey and the recovery code, the notes are gone. Nobody can reset what the server can't read. That one is the point, but it deserves to be said in plain sentences.

Where this pattern goes

The interesting part isn't notes. Passkeys quietly solved key distribution: key material that syncs across your devices, survives losing one, and unlocks with a fingerprint. The ecosystem uses all of that for login and nothing else. Anything that currently makes a user manage a key file, a seed phrase, or a master password is a candidate for this same PRF-to-KEK construction, and notes were just the version I needed.

Code and threat model are in the repo. If you spot a hole in the crypto, the repo has private vulnerability reporting, and I'd genuinely rather hear it from you than find it in a postmortem.

My "Deploy to Cloudflare" button disabled auth

Daniel Yang — Fri, 10 Jul 2026 01:54:20 +0000

I recently open-sourced Minvoice, a small invoicing app that runs entirely on Cloudflare Workers. Like every well-behaved open-source Workers project, it has a Deploy to Cloudflare button in the README: one click, and you get the repo forked to your GitHub, a D1 database provisioned, and the app running on your own workers.dev subdomain.

I clicked my own button to test it. The deploy went fine. The app came up, the setup wizard ran, invoices saved. Then I opened /admin on the fresh deployment and walked straight in, past no login screen of any kind. Every copy of my app deployed through that button had admin auth turned off.

How it happened

The deploy button does something that sounds reasonable: it reads your .dev.vars.example file, prompts the deployer for each entry as a required secret, and deploys those values with the Worker.

Here's what my .dev.vars.example looked like at the time:

DEV_BYPASS_ACCESS=true
APP_BASE_URL=http://localhost:8787
STRIPE_SECRET_KEY=sk_test_xxx
STRIPE_WEBHOOK_SECRET=whsec_xxx
PAYPAL_CLIENT_ID=sandbox_client_id
PAYPAL_CLIENT_SECRET=sandbox_client_secret
PAYPAL_WEBHOOK_ID=sandbox_webhook_id

That file is a normal local-development template, and on its own it's inert — nothing reads it. You copy it to .dev.vars (gitignored), adjust the values, and the copy is what wrangler dev loads. The values are pre-filled so the copy works immediately: DEV_BYPASS_ACCESS=true skips auth in local dev, because nobody wants to click through a login screen a hundred times a day.

The deploy button doesn't know any of that. It saw seven config entries and prompted for all seven, with the example values pre-filled as suggestions. Most people deploying someone else's app for the first time accept the defaults. So the deployed Workers got:

DEV_BYPASS_ACCESS=true as a production secret. My auth middleware checked env.DEV_BYPASS_ACCESS === 'true' and skipped verification. The admin was wide open.
APP_BASE_URL=http://localhost:8787. Every pay link the app generated, in emails, in PDFs, on the copy-link button, pointed at localhost.
Placeholder API keys that passed the "is it configured?" checks. sk_test_xxx is a truthy string, so the app rendered payment buttons that would fail the moment a client tried to pay.

Three failures, one root cause: template text that was only ever meant to be copied and edited by a human became someone else's production configuration, with the editing step removed. Nothing in the pipeline knew the difference.

The fix took three layers

My first instinct was to fix the example file and move on. That's the right first step, and it is nowhere near enough. If a one-click deploy can turn example values into production config, the app has to survive that on its own. Hoping the example file stays clean forever is not a plan.

Layer 1: treat the example file as an installer

Once a deploy button exists, .dev.vars.example stops being documentation. It's the installer prompt. So now only the one value a first deploy genuinely needs is active, and everything else is commented out with instructions:

# NOTE: the Deploy to Cloudflare button prompts for every UNCOMMENTED entry
# as a required secret — so only the true first-deploy requirement is active.

# Admin login until Cloudflare Access is configured (Access disables it)
ADMIN_PASSWORD=

# ---- Payments: add when ready ----
# STRIPE_SECRET_KEY=
# ...

The button now prompts for exactly one thing, an admin password. The app's dashboard warns about everything else until it's configured.

Layer 2: make the bypass flag useless on a deployed Worker

Even if DEV_BYPASS_ACCESS=true gets deployed again someday (someone copies a config, a fork resurrects the old example file), it must not matter. The flag now only counts when the request is genuinely local:

export function devBypassActive(env, req): boolean {
  return env.DEV_BYPASS_ACCESS === 'true' && isLocalRequest(req);
}

This is the part that surprised me. My first version of isLocalRequest checked the URL hostname, and it broke immediately in local development, because wrangler dev emulates your configured route host in request.url. A request to localhost:8787 shows up inside the Worker as https://your-production-domain.com/.... On Workers, hostname checks can't tell local from production.

The signal that works is the cf-ray header:

/** Local dev request: localhost hostname, or no cf-ray (never traversed the edge). */
export function isLocalRequest(req): boolean {
  const host = new URL(req.url).hostname;
  if (host === 'localhost' || host === '127.0.0.1' || host === '[::1]') return true;
  return !req.headers.get('cf-ray');
}

Every request that traverses Cloudflare's edge carries cf-ray, and a client can't strip it; the edge adds it after the client's headers are already fixed. No cf-ray means the request never touched the edge, which means it's local. The same signal later fixed a second bug (localhost pay links in a different code path), and I now treat any hostname-based branching in Workers code as a smell worth auditing.

Layer 3: reject placeholder secrets

The payment buttons rendered because the code asked whether a Stripe key existed, and sk_test_xxx is, technically, a string. The configuration checks now reject known placeholder shapes:

const PLACEHOLDER_VALUES = new Set([
  'sk_test_xxx',
  'whsec_xxx',
  'sandbox_client_id',
  // ...
]);

export function secretConfigured(v: string | undefined): boolean {
  const t = (v ?? '').trim();
  return t !== '' && !PLACEHOLDER_VALUES.has(t);
}

The same idea protects auth-mode selection. Placeholder Access values from the example wrangler config don't count as configured (the AUD has to actually look like a 64-character hex AUD), so the app can't be tricked into a half-configured auth mode. Base-URL resolution got the same treatment: a localhost value arriving on a request that came through the edge gets ignored in favor of the request origin.

Each layer covers a hole the others leave. The example file can regress; layer 2 doesn't care. The bypass flag can leak; layer 1 makes it unlikely and layer 2 makes it inert. A placeholder can slip through a prompt; layer 3 keeps it from pretending to be real. All three now have unit tests with names like "never active for requests that traversed the Cloudflare edge" and "placeholder Access values do not count as configured". You only write tests like that after the incident that makes them obvious.

What I'd ask of the platform

None of this is really a Cloudflare bug. The docs do say secrets come from .dev.vars.example — I put dev conveniences in a file that feeds the installer, and that's on me. What the docs don't say is that every entry becomes a required prompt with the example value pre-filled, and there's no way to mark one optional. Two small changes would have prevented the whole class of problem:

An optional-secrets flag. Deploy buttons currently treat every .dev.vars.example entry as required. A way to mark entries optional (or a documented convention of skipping commented entries, which is effectively what I reverse-engineered) would let template authors separate "needed to boot" from "add later."
A loud warning in the deploy-button docs that .dev.vars.example becomes a production prompt. Every Workers template with local-dev conveniences in its example file is one deploy button away from this postmortem.

I've filed both: the docs warning and the optional-secrets feature request. If you maintain a Workers template with a deploy button, go look at your example file right now.

The lesson

The general version of this incident: distribution inverts your threat model. The moment you add a one-click deploy path, every convenience you built for yourself gets inherited by people who don't know it exists. Your example files, your defaults, the flags nobody would ever set in production. All of it ships.

So design the example file like it's an installer, and gate the dangerous flags on signals that can't be faked. A variable existing was never the same thing as a variable being real.

Minvoice is open source on GitHub. The fix commits and the tests are all there if you want the details.