glyphlock 0.1.2

Glyph-based file obfuscation with intentional access control

Glyphlock

This module contains a simple implementation of glyph-based file obfuscation with optional access control.

---

What glyphlock does

Glyphlock converts a file into a deterministic representation made up of Unicode Egyptian hieroglyphs.

The original file:

• is removed
• is replaced with a .glyph file
• is no longer readable as plain text

The transformation is fully reversible and does not modify the original data.

---

What glyphlock is for

Glyphlock is meant to prevent accidental or casual access to files.

It is designed to be used when:

• files should not be readable at a glance
• sensitive data should not be opened unintentionally
• projects need to be parked safely on disk
• access should require intent

This tool is not encryption and is not designed to protect against determined offline attacks.

---

Access control

Glyphlock supports optional access gating.

When enabled:

• a password is required to decode files
• passwords are verified using a key derivation function
• passwords are never stored directly

An optional recovery key can also be generated.

The recovery key:

• is shown once
• is stored as a hash
• can be used if the password is lost

If both the password and recovery key are lost, the file cannot be recovered.

---

File behavior

When encoding:

• the original file is replaced with filename.glyph
• the original file extension is stored in the header
• file permissions are preserved
• the file payload is checksummed

When decoding:

• the original file is restored exactly
• permissions are restored
• corrupted or modified files fail to decode

All file operations use atomic replacement to minimize the risk of data loss.

---

Directory handling

When operating on directories, glyphlock walks the directory tree recursively.

The following are skipped automatically:

• symbolic links
• hidden directories
• version control metadata (.git, .hg, .svn)
• virtual environments (.venv, env)
• Python cache directories (__pycache__)
• editor configuration directories

Only user-authored files are processed by default.

---

How to use this module

Glyphlock is used as a command-line tool. Only the encode and encode-directory commands accept access flags. All commands accept --plan flags.

Encode a single file:

glyphlock encode file.txt

Decode a file (decode commands do not accept access flags):

glyphlock decode file.glyph

Encode a directory with a password and recovery key:

glyphlock encode-dir project --lock --recovery

Decode a directory (decode commands do not accept access flags):

glyphlock decode-dir project

---

Access flags

The following flags are supported when encoding files or directories:

• --lock
  Require a password to decode the file(s).

• --recovery
  Generate a recovery key that can be used if the password is lost.

When operating on directories:

• the password is requested once per command
• the recovery key (if enabled) is generated once per command
• the same access credentials apply to all files in the operation

When operating on a single file:

• the same flags apply, but only affect that file

---

Planning and dry runs

Glyphlock supports a --plan flag for all commands.

When --plan is used:

• no files are modified
• no passwords are requested
• no recovery keys are generated
• the operation is printed instead of executed

This allows you to preview exactly what glyphlock would do.

Examples:

glyphlock encode file.txt --plan
glyphlock encode-dir project --plan
glyphlock decode-dir project --plan

---

Security note

Glyphlock is not encryption.

It is designed to prevent casual or accidental access, not to withstand determined cryptographic attacks.

If you require strong confidentiality against an active adversary, use established encryption tools such as age, gpg, or full-disk encryption.